$ guides / uwsgi / uwsgi-harakiri-timeout-tuning ▌

Operations Guides

uWSGI harakiri timeout: setting it against request duration and nginx timeouts

The harakiri timeout is uWSGI’s per-request watchdog: if a request runs longer than the configured threshold, the master kills the worker (SIGKILL by default) and respawns it. Without it, a hung worker stays hung indefinitely, consuming a slot in the pool until every worker is stuck and the service is dark.

Harakiri has to sit in a narrow band: above the p99 of legitimate requests so you do not kill real traffic, but below the point where the upstream proxy gives up. If nginx’s uwsgi_read_timeout fires first, you get a 504 while the uWSGI worker keeps processing a response nobody will read. If harakiri fires first, nginx sees an upstream disconnect and returns a 502. The capacity implications differ: a 504 means wasted work, a 502 means a recycled worker.

This article covers how to choose the harakiri value, how it interacts with nginx timeouts, and how to handle legitimately long endpoints without raising the global ceiling.

What it is and why it matters

Harakiri is configured with the harakiri option (seconds). When a worker’s current request exceeds that duration, the master kills the worker and forks a replacement. The kill increments the worker’s harakiri_count (monotonic, never reset, even on respawn) and respawn_count. The client gets nothing; the connection closes mid-response.

Default uWSGI ships with harakiri disabled. A deployment with no harakiri has no automatic timeout for stuck requests. The harakiri_count stat stays permanently zero, which looks like health but is a blind spot. See uWSGI monitoring checklist: the signals every production app server needs for the full set of signals this obscures.

How it works

The harakiri mechanism has two modes:

Without a master process: uses SIGALRM-based timing. The uWSGI FAQ describes this as “raw and a bit unreliable.”
With a master process (--master): the master tracks each worker’s current request start timestamp in mmap’d shared memory and enforces the timeout centrally. This is the mode you should be running in production.

When the timeout fires, the default behavior is immediate SIGKILL. The worker has no chance to clean up database connections, release locks, or flush buffers. uWSGI 2.0.22 added three graceful options:

harakiri-graceful-timeout: the master first sends SIGTERM (configurable via the next option) and waits this many seconds before falling back to SIGKILL.
harakiri-graceful-signal: the signal to send first (defaults to SIGTERM).
harakiri-queue-threshold: only trigger harakiri when the listen queue exceeds a threshold.

If none of these are set, harakiri uses immediate SIGKILL with no cleanup.

The harakiri-verbose option (Linux only) logs the blocked syscall and wait channel by reading /proc/<pid>/syscall and /proc/<pid>/wchan at kill time. Essential for diagnosing what the worker was stuck on. Without it, the log tells you a worker was killed but not why.

The nginx timeout race

When uWSGI sits behind nginx, two independent timeouts race on every request:

flowchart TD
    REQ[Incoming request] --> NGX[nginx starts uwsgi_read_timeout]
    NGX --> WRK[uWSGI worker starts harakiri timer]
    WRK --> RACE{Which fires first?}
    RACE -->|nginx read timeout elapses| N504[nginx returns 504 Gateway Timeout
worker still processing
wasted capacity until harakiri or completion]
    RACE -->|harakiri elapses first| H502[master SIGKILLs worker
nginx sees upstream disconnect
returns 502 Bad Gateway]

Nginx’s uwsgi_read_timeout defaults to 60 seconds. So do uwsgi_send_timeout and uwsgi_connect_timeout. If you set harakiri = 60 and leave nginx at default, you have a near-tie and boundary behavior is nondeterministic under load.

Set harakiri slightly below the nginx read timeout. This ensures uWSGI reclaims the worker and nginx sees a clean upstream disconnect (502) rather than timing out itself (504). A 504 with the worker still running means the worker is producing output that will be discarded. A 502 is the more honest signal: the upstream failed, and the worker has already been recycled.

Where it shows up in production

Harakiri death spiral. A downstream dependency (database, external API) goes unresponsive. Every request blocks on the dependency, exceeds the timeout, and the worker is killed. The master respawns the worker, which immediately accepts a queued request that also blocks. Throughput collapses to near zero. See uWSGI HARAKIRI ON WORKER: requests killed for exceeding the timeout. The harakiri value sets the cycle time: a 60-second harakiri means each worker burns a full minute per request before recycling. A 10-second harakiri recycles faster but generates more errors per unit time. Neither fixes the root cause.

Legitimate long endpoints. Report generation, CSV exports, bulk API calls, and file processing routinely exceed 30 to 60 seconds. If the global harakiri is set for the common case (say 15 seconds for a CRUD API), these endpoints are killed on every invocation. The symptom is intermittent 502s on specific routes while the rest of the service is healthy.

Nginx 504 storms with high harakiri. If harakiri is set to 300 seconds to accommodate slow reports and nginx is left at its 60-second default, nginx returns 504 for any request exceeding 60 seconds. The worker continues processing for up to 300 seconds on a response that will never reach the client. Workers are busy producing output that gets thrown away.

Setting the value

Picking the global value

Set harakiri above the p99 of legitimate request duration and well below the point where upstream proxies give up. For a typical web API with p99 latency under 2 seconds, a harakiri of 15 to 30 seconds gives headroom for transient slowdowns while catching genuinely stuck requests.

Do not use the average request time. Harakiri is about the tail. Use access-log percentiles (p99 or p99.9) per endpoint, not uWSGI’s avg_rt stat. The avg_rt field is an exponential moving average computed as (old_avg_rt + current_request_time) / 2, giving approximately 50% weight to the most recent request. After about 7 requests, older contributions are negligible. A single slow request shifts it significantly. It is too volatile for latency SLIs.

Reconciling with nginx

The ordering should be:

p99 request duration < harakiri < uwsgi_read_timeout < user patience

A practical starting point: if your p99 is 2 seconds, set harakiri = 15 and uwsgi_read_timeout = 20, then adjust based on observed harakiri and 502 rates. The gap gives the master time to kill the worker, recycle it, and close the connection before nginx’s own timer fires.

If you need to support long endpoints globally, raise both values together. harakiri = 120 with uwsgi_read_timeout = 125 supports two-minute endpoints. But a death spiral then burns two minutes per worker per cycle. Prefer per-route configuration instead.

Per-route harakiri for long endpoints

uWSGI supports per-route harakiri via the internal routing system. The harakiri action overrides the global timeout for matching requests:

; Global timeout for normal requests
harakiri = 15

; Longer timeout for specific endpoints
route = ^/reports/ harakiri:120
route = ^/api/export/ harakiri:180

This keeps a tight global timeout for the majority of traffic while accommodating specific slow endpoints. The nginx side needs matching uwsgi_read_timeout values per location block.

Known bug (uWSGI 2.0.25.1, GitHub issue #2680): when both a global harakiri and a route-level harakiri action are set, GET requests to the matched route still get killed at the global timeout. POST requests respect the route-level value. The workaround is to either avoid setting a global harakiri when using per-route values, or set the global value as the minimum and use route harakiri only for endpoints that need more time.

uWSGI issue #2680 remains open with no fix released through the 2.0.x line (2.0.31); test the behavior in your specific build before relying on route-level values for GET requests.

Dedicated worker pools

An alternative to per-route harakiri is running a separate uWSGI instance for long-running endpoints. This isolates capacity: if report generation ties up workers, it does not consume slots from the main API pool. Heavier to operate (two instances, two configs, two monitoring targets) but cleaner for workloads where long requests are a significant fraction of traffic.

Graceful harakiri (uWSGI 2.0.22+)

If your application holds resources that must be cleaned up (database connections, distributed locks, temporary files), the default SIGKILL leaves them dangling. Setting harakiri-graceful-timeout = 5 sends SIGTERM first, giving the worker a short window to run signal handlers before the master forces the kill.

The behavior of graceful harakiri with async modes (gevent, asyncio) is not fully documented. Reports on GitHub issue #2606 (open, reported on uWSGI 2.0.19 through 2.0.24) indicate that in some gevent configurations the graceful timeout fell through to immediate SIGKILL regardless of the setting. Test with your specific stack before relying on it.

Harakiri firing early

GitHub issue #2606 (open) documents operators seeing harakiri trigger 1 to 2 seconds after request start despite harakiri = 300, across uWSGI 2.0.19 through 2.0.24. CPU throttling in containerized deployments was raised in the thread as a possible cause; one reporter tested it and found no throttling in their environment, so no single trigger was confirmed there. No official fix has been released through the 2.0.x line. If you see harakiri firing well below your configured value in a containerized environment with CPU limits, investigate CPU throttling.

Signals to watch

Signal	Why it matters	Warning sign
`harakiri_count` delta (per worker)	Direct measure of how often requests hit the timeout	Any sustained non-zero rate in a normally-zero deployment
`respawn_count` delta vs `harakiri_count` delta	If respawns track harakiri 1:1, kills are the primary churn source	Respawn rate exceeding expected max-requests recycling cadence
nginx 502 rate	Harakiri fired before nginx timed out	Spike correlating with harakiri count increase
nginx 504 rate	nginx timed out before harakiri fired	Sustained 504s indicate harakiri set too high relative to nginx timeout
`avg_rt` (per worker, microseconds)	Approaching harakiri means workers are about to die	Sustained avg_rt within 2-3x of configured harakiri
Stuck request age (`cores[].req_info.request_start`)	Elapsed time of in-flight requests	Any request age approaching harakiri threshold
Worker busy ratio	High busy ratio with rising harakiri signals a death spiral	Busy ratio above 80% with non-zero harakiri delta

The harakiri_count counter is per-worker and monotonic. It never resets, even on respawn. Track the rate (delta over a polling window), not the absolute value. See uWSGI all workers busy: reading the busy ratio before the queue fills for how to interpret busy ratio alongside harakiri trends.

How Netdata helps

Per-second harakiri_count deltas expose harakiri storms as they form. The per-worker breakdown shows whether kills are concentrated on specific workers (request-pattern issue) or spread evenly (systemic dependency failure). Correlating avg_rt with harakiri rate shows whether rising latency is about to cross the timeout boundary, giving lead time before workers start dying. Decomposing respawn rate separates harakiri-driven respawns from max-requests recycling and crash-driven respawns. Worker busy ratio alongside harakiri count distinguishes a death spiral (busy at 100%, harakiri rising, throughput collapsing) from isolated slow requests (busy ratio moderate, harakiri concentrated on one or two workers). Stuck request age tracking via per-core in_request and req_info.request_start shows how long in-flight requests have been running, the most direct leading indicator that harakiri is about to fire on specific workers.