uWSGI max-requests: worker recycling that masks leaks and crashes

You set max-requests because it bounds memory leaks in uWSGI workers. Workers recycle on schedule. But max-requests does not fix leaks. It bounds them by killing the worker before the leak becomes fatal.

Two blind spots follow. First, peak RSS per worker is leak_rate x max_requests, not zero. At 1MB leaked per request and max-requests 1000, each worker reaches roughly 1GB before recycling. With 8 workers, that is 8GB consumed by leak tolerance alone. Second, the respawn activity from max-requests looks identical to crash churn in the stats server. If workers are also dying from segfaults, OOM kills, or harakiri timeouts, the respawn counter alone cannot tell you why.

The goal: calculate the peak RSS that max-requests implies, correlate the signals that separate recycling from crashes, and add reload-on-rss as a memory-based safety net.

What this means

max-requests tells each worker to self-exit gracefully after serving N requests. The worker finishes its current request, then exits. The master forks a replacement. This is a clean exit, not a mid-request kill.

The option accepts a 64-bit integer. The shortcut is -R.

Each recycling increments the worker’s respawn counter, which is the same counter that increments when a worker crashes, gets harakiri-killed, or is recycled by reload-on-rss. Without knowing the max-requests configuration and correlating with harakiri events, the respawn signal alone cannot tell you why workers are cycling.

The key insight: max-requests controls when recycling happens, not how much memory workers accumulate before recycling. If your application leaks, each worker grows steadily until it hits the request limit and exits. The sawtooth RSS pattern this produces looks healthy because the system survives. But the peak RSS is a direct function of your max-requests setting and the leak rate.

Common causes

Quick checks

# List available stats fields for your version (verify before relying on specific names)
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.workers[0] | keys'

# Check max-requests and related memory recycling settings
grep -i 'max.requests\|max-worker-lifetime\|reload-on-rss\|min-worker-lifetime' /etc/uwsgi/apps-enabled/*.ini

# Aggregate respawn count (monotonic per worker slot; poll twice and compute delta)
uwsgi --connect-and-read 127.0.0.1:9191 | jq '[.workers[].respawn_count] | add'

<!-- Per-worker `harakiri_count` is present in standard uWSGI stats output; the log-based detection below complements it. -->

# Check for harakiri events in logs (stats server may not expose a cumulative harakiri count)
grep -i harakiri /var/log/uwsgi/*.log | tail -20

# Per-worker RSS and request count to see the sawtooth
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.workers[] | select(.pid > 0) | {id: .id, rss_mb: (.rss / 1048576), requests: .requests}'

# Per-worker respawn vs requests to check whether respawns track max-requests
uwsgi --connect-and-read 127.0.0.1:9191 | jq '.workers[] | {id: .id, respawn_count: .respawn_count, requests: .requests}'

# Accepting worker count (capacity during recycling)
uwsgi --connect-and-read 127.0.0.1:9191 | jq '[.workers[] | select(.pid > 0 and .status != "cheap" and .accepting == 1)] | length'

# Check for OOM kills that max-requests should have prevented
dmesg -T | grep -i 'oom.*killed\|out of memory' | tail -20

If your stats socket is a UNIX socket, replace 127.0.0.1:9191 with the socket path or use socat - UNIX-CONNECT:/path/to/stats.sock. If --stats-http is enabled, curl http://127.0.0.1:9191 also works.

How to diagnose it

The diagnostic goal is to separate expected recycling from failure churn, and to measure the leak that max-requests is bounding.

flowchart TD
    A["Observe worker respawns"] --> B{"Harakiri evidence in logs?"}
    B -->|"Yes, tracks respawn rate"| C["Crash churn: timeouts causing kills"]
    B -->|"No harakiri"| D{"Respawn rate matches expected cadence?"}
    D -->|"Yes"| E["Expected max-requests recycling"]
    D -->|"No, higher than expected"| F["Investigate: OOM, segfaults, reload-on-rss"]
    E --> G{"Per-worker RSS near peak?"}
    G -->|"Yes, sawtooth with high peaks"| H["Leak masked by recycling"]
    G -->|"No, stable"| I["Healthy operation"]

1. Confirm the max-requests value. Check the configuration. Without knowing N, you cannot compute the expected respawn rate or the peak RSS the setting implies.

2. Calculate expected respawn rate. With max-requests = 1000 and 100 req/s across all workers, expect roughly 0.1 respawns/s (one recycling event per 10 seconds). If observed respawns are significantly higher, something else is killing workers.

3. Separate harakiri-driven respawns from recycling. Every harakiri kill increments the respawn counter. If the stats server exposes a per-worker harakiri count, compute respawn_delta - harakiri_delta. If the remainder matches your expected max-requests rate and harakiri is zero, recycling is the only cause. If the remainder is near zero and harakiri is positive, workers are dying from timeouts. If the stats server does not expose a harakiri count, cross-reference harakiri log entries against respawn timestamps.

4. Check per-worker RSS for the sawtooth. Healthy max-requests recycling produces a sawtooth: RSS rises linearly as the leak accumulates, then drops sharply when the worker exits and a fresh one starts. The peak of each tooth is the number that matters. If peaks approach system memory limits or your reload-on-rss threshold, the leak is growing faster than max-requests can safely bound.

5. Check for simultaneous recycling. If all workers receive similar traffic, they reach max-requests at nearly the same time and exit together. The master must fork all replacements before capacity returns. Look for brief periods where accepting worker count drops sharply. The fix is staggering (see below).

6. Check OOM evidence. If workers are being OOM-killed despite max-requests being configured, peak RSS is exceeding system limits. Either lower max-requests, add reload-on-rss as a secondary bound, or fix the leak.

Metrics and signals to monitor

Fixes

Calculate peak RSS before setting max-requests

The formula: peak_rss_per_worker = leak_rate_per_request x max_requests. Multiply by worker count for total memory consumed by leak tolerance.

Example: 1MB leaked per request, max-requests = 1000, 8 workers. Each worker reaches 1GB before recycling. Total peak worker RSS from the leak alone is 8GB. If the system has 16GB and the application base RSS is 200MB per worker (1.6GB total), the combined peak is 9.6GB. That may be fine. At 4MB leaked per request with the same settings, each worker reaches 4GB, total peak is 32GB plus base, and you OOM.

To measure leak rate: poll per-worker RSS at fixed intervals, divide RSS growth by request count over the same interval.

Add reload-on-rss as a memory-based bound

max-requests bounds leaks by request count. reload-on-rss bounds them by actual memory. The two are complementary. Set reload-on-rss to a value below the OOM danger zone so that if the leak rate is higher than expected, workers recycle on memory before the kernel kills them.

This combination is community guidance, not an official uWSGI recommendation; treat the values as starting points. Some production deployments use reload-on-rss = 2048 alongside max-requests = 1000 and max-worker-lifetime = 3600. Treat these as starting points, not prescriptions. Measure your own leak rate and capacity before applying.

reload-on-rss is graceful: the worker finishes its current request, then exits. evil-reload-on-rss does the same but via SIGKILL mid-request. Do not confuse them. If you use evil-reload-on-rss, clients will see broken responses during kills; monitor connection errors alongside respawn rates.

Lower max-requests when leak rate is high

If peak RSS under the current setting is too high, lowering max-requests reduces the peak at the cost of more frequent recycling. More recycling means more capacity dips during worker replacement, especially if workers restart slowly (heavy imports, lazy-apps mode). Balance the two.

Stagger recycling with max-requests-delta

Without staggering, workers that receive similar traffic reach max-requests at nearly the same time. All exit together and the master must fork all replacements before capacity returns. During that window, accepting worker count drops and the listen queue fills.

max-requests-delta adds worker_id x delta to each worker’s max-requests value, staggering recycling across workers. This option has significant version caveats:

• It is a uWSGI 2.1 feature that was not available in 2.0.x releases before 2.0.29.
• In 2.0.x strict mode, the option is rejected with [strict-mode] unknown config directive: max-requests-delta on versions before 2.0.29.
• uWSGI 2.0.29 (April 2025) backported --max-requests-delta from master (the 2.0.29 release notes spell it “–max-request-delta”, but the option as shipped in 2.0.29 and later is max-requests-delta). Strict mode accepts the 2.0.29 backport because it is a registered option; only pre-2.0.29 versions reject it with [strict-mode] unknown config directive. The delta mechanism adds (worker_id * delta) to each worker’s max-requests (2.0.29+ and master), which staggers recycling; issue #648 describes the un-staggered simultaneous recycling this option solves.

If you are on a 2.0.x version without delta support, consider max-worker-lifetime (which recycles workers after a time interval, not a request count) or run multiple uWSGI instances behind a load balancer with different max-requests values.

Account for min-worker-lifetime

Verified in source: min-worker-lifetime defaults to 10 seconds in both 2.0.x and master (the options reference says 60, which is stale relative to the code), and it does gate recycling: a worker is only recycled once its minimum lifetime has elapsed, even if max-requests was reached first. min-worker-lifetime prevents workers from being recycled too soon after starting. If configured, a worker that reaches max-requests before its minimum lifetime expires will not be recycled until that lifetime elapses. This prevents respawn storms during traffic bursts but can confuse benchmarking and low-traffic investigations where you expect recycling to happen faster.

Prevention

• Calculate peak RSS before deploying. Measure the leak rate and compute leak_rate x max_requests x workers. If that number is close to system memory, lower max-requests or add reload-on-rss.
• Correlate respawn and harakiri evidence in monitoring. A respawn rate without harakiri context is uninterpretable. Your monitoring must separate harakiri-driven respawns from recycling to isolate the cause.
• Track per-worker RSS, not just aggregates. The sawtooth pattern is diagnostic. Aggregate RSS hides individual worker peaks. Watch the peak of each tooth, not the average.
• Set reload-on-rss as a secondary bound. It catches leaks that grow faster than expected, recycling workers on actual memory usage before the kernel OOM-killer does.
• Know your uWSGI version. The max-requests-delta availability differs between 2.0.x and 2.1, and between strict and non-strict mode. Check before relying on it.
• Do not treat max-requests as a leak fix. It is a bound, not a fix. Profile memory with tracemalloc (Python) or equivalent and address the source.

How Netdata helps

Netdata provides the signals needed to distinguish healthy max-requests recycling from masked failures:

• Per-worker RSS at per-second resolution reveals the sawtooth pattern and its peak. The peak of each tooth is the number that matters for capacity planning.
• Respawn rate tracked as deltas lets you compare against the expected max-requests cadence. If the observed rate exceeds what max-requests alone would produce, something else is killing workers.
• Accepting worker count shows the capacity impact of recycling events. Brief dips during single-worker recycling are normal. Sustained drops indicate simultaneous recycling or a respawn bottleneck.
• Worker busy ratio correlated with respawn events distinguishes recycling-induced capacity dips from genuine worker exhaustion.
• Per-worker metrics, not just aggregates, ensure a single worker with a runaway leak or stuck state is visible rather than diluted into a fleet average.

Related guides

• uWSGI all workers busy: reading the busy ratio before the queue fills
• uWSGI connection refused: clients turned away when the backlog overflows
• uWSGI harakiri death spiral: workers killed and respawned while throughput collapses
• uWSGI harakiri not configured: stuck workers with no timeout and no recovery
• uWSGI harakiri timeout: setting it against request duration and nginx timeouts
• uWSGI harakiri-verbose: finding the blocked syscall behind a timeout
• uWSGI HARAKIRI ON WORKER: requests killed for exceeding the timeout
• How uWSGI actually works in production: a mental model for operators
• uWSGI listen backlog and net.core.somaxconn: sizing the connection queue
• uWSGI listen queue full: the backlog overflow that drops connections silently
• uWSGI listen_queue always zero: why the stats field is broken on Linux
• uWSGI master process dead: total outage while the PID file lingers