uWSGI Operations Guides on Netdata

How uWSGI actually works in production: a mental model for operators

Mon, 01 Jan 0001 00:00:00 +0000

uWSGI is a pre-fork application server. A single master process spawns a pool of worker processes, each running a full copy of your application. The master never serves requests. It manages worker lifecycle, enforces timeouts, and coordinates graceful reloads. Every request flows through the same path: a client connects to a socket, the kernel queues that connection in a listen backlog, and a worker calls accept() to pull it out and process it synchronously.

uWSGI all workers busy: reading the busy ratio before the queue fills

Mon, 01 Jan 0001 00:00:00 +0000

When every uWSGI worker shows status: "busy", the next incoming request does not wait in a place you can see. It lands in the kernel socket backlog, which uWSGI cannot reliably measure on standard Linux. If that backlog fills, the kernel drops connections silently. No log entry, no error counter, no uWSGI-level signal. The application looks alive but stops serving real traffic.

The worker busy ratio is the earliest internal indicator that you are approaching that cliff. It tells you what proportion of your alive, non-cheaped workers are currently processing requests. Reading it correctly requires understanding what “busy” actually means, what it does not mean, and where the visibility gap starts.

uWSGI avg_rt is not a real average: why the latency number lies

Mon, 01 Jan 0001 00:00:00 +0000

uWSGI exposes a per-worker field called avg_rt in its stats server JSON. Most monitoring tools label it “average response time” and graph it as a latency indicator. It is not a cumulative or lifetime average.

The field is updated with the formula (old_avg_rt + current_request_time) / 2, an exponential moving average with a smoothing factor of 0.5. The most recent request contributes 50% of the displayed value. The request before that contributes 25%. By the seventh request back, the contribution is under 1%.

uWSGI behind nginx: 502 Bad Gateway and 'upstream prematurely closed connection'

Mon, 01 Jan 0001 00:00:00 +0000

The error string upstream prematurely closed connection while reading response header from upstream in the nginx error log means nginx had an established connection to a uWSGI worker, the worker accepted the request, and then the connection closed before nginx received a complete response header. The worker vanished mid-response.

This is distinct from two other errors that also produce 5xx responses but have different root causes:

nginx log string	HTTP status	What happened	Where to look
`upstream prematurely closed connection while reading response header from upstream`	502	Worker accepted the request, then died mid-response	uWSGI stats: `harakiri_count`, `respawn_count`; `dmesg`
`connect() ... failed (111: Connection refused) while connecting to upstream`	502	No connection established: uWSGI not listening, socket permissions, or backlog full	Master alive? Socket perms? `ss -ltn`
`upstream timed out (110: Connection timed out) while reading response header from upstream`	504	Worker accepted but did not finish within nginx’s timeout	uWSGI stats: worker busy ratio, `avg_rt`

This article covers the first row only. The root cause is always on the uWSGI side. The worker was killed by harakiri, crashed with a segfault, was killed by the kernel OOM killer, or was SIGKILL’d by the master enforcing an evil-reload-on-rss threshold. Diagnose from uWSGI, not from nginx.

uWSGI behind nginx: 504 Gateway Timeout when uwsgi_read_timeout fires first

Mon, 01 Jan 0001 00:00:00 +0000

A 504 from nginx with a uwsgi_pass upstream means nginx stopped waiting for uWSGI before the worker finished. The default uwsgi_read_timeout is 60 seconds. If uWSGI has no harakiri configured (the default), or if harakiri is set higher than uwsgi_read_timeout, the worker keeps processing a request whose response will never be read. The client already has their 504. The worker burns CPU, holds database connections, and occupies a slot that could serve real traffic.

uWSGI cache subsystem: hit ratio drops and 'full' insert failures

Mon, 01 Jan 0001 00:00:00 +0000

Response times are creeping upward on cached endpoints. Application logs show nothing. Worker busy ratio is normal. The cause is likely silent: uWSGI cache misses are increasing, and each miss forces the worker to compute or fetch the response instead of serving from shared memory.

This article covers uWSGI’s built-in cache subsystem (cache2), not external caches. If caches[] is absent from the stats server output, the uWSGI cache is not enabled and these diagnostics do not apply.

uWSGI capacity planning: the leading indicators before saturation

Mon, 01 Jan 0001 00:00:00 +0000

uWSGI does not degrade gracefully. Performance looks fine until a hard limit is reached, then the service drops requests, kills workers, or refuses connections. Capacity planning is about knowing where each cliff is, measuring how close you are, and adding capacity before the edge.

Four resources saturate as cliffs: worker pool (concurrency), memory (per-worker RSS), socket backlog (kernel listen queue), and file descriptors. Each has a distinct failure mode, leading indicator, and measurement method. Some signals come from the uWSGI stats server JSON. Others require external tools because uWSGI’s internal measurement is broken or silent.

uWSGI chain reload: cycling workers one at a time for zero-downtime deploys

Mon, 01 Jan 0001 00:00:00 +0000

The default uWSGI graceful reload sends all workers the shutdown signal at once. Each worker finishes its current request, exits, and the master forks a replacement. During the gap between old workers dying and new workers becoming ready to accept connections, serving capacity falls to zero. For applications with fast startup, this gap is a brief hiccup. For applications that load large models, warm connection pools, or run heavy imports on startup, the gap can stretch into seconds or minutes of complete unavailability.

uWSGI cheaper subsystem: dynamic worker scaling and the false 'missing workers' alert

Mon, 01 Jan 0001 00:00:00 +0000

The uWSGI cheaper subsystem dynamically scales the worker pool up and down at runtime based on demand. The master process spawns additional workers when traffic increases and reaps them when it subsides, reducing memory consumption during idle periods and providing automatic capacity during bursts.

When the cheaper subsystem is active, the number of alive workers fluctuates by design. Cheaped workers (those scaled down by the subsystem) appear in the stats server output with "status":"cheap" and "pid":0. Monitoring that expects a fixed worker count will fire false “missing workers” alerts every time the system scales down.

uWSGI connection pool cascade: downstream latency that stalls every worker

Mon, 01 Jan 0001 00:00:00 +0000

Workers climbing toward all-busy. Response times creeping up. Throughput falling. No traffic spike, no deploy, no code change. The pattern built over minutes, not seconds.

The mechanism is a reinforcing feedback loop. A downstream dependency (database, cache, external API) gets slower. Not dead, just slower. Each request now holds its downstream connection longer. The pool fills. The next request that needs a connection blocks waiting for one to be returned. That wait adds to the request’s wall-clock duration, which keeps the worker busy longer, which keeps the connection occupied longer. The loop tightens until every worker is blocked on pool checkout and throughput collapses.

uWSGI connection refused: clients turned away when the backlog overflows

Mon, 01 Jan 0001 00:00:00 +0000

Clients connecting to your uWSGI application receive connection refused or TCP RST. Behind nginx, the error log shows connect() failed (111: Connection refused) while connecting to upstream. The application process may still be running, the master PID may exist, and the stats server may respond, yet real traffic is being turned away.

This symptom has two root causes that look identical to the client but require opposite fixes. Either the listen backlog has overflowed because workers are saturated and cannot call accept() fast enough, or the listener itself is dead (master gone, wrong socket path, broken socket permissions). Resolving that diagnostic fork is the first task.

uWSGI dropped connections: reading TcpExtListenOverflows and ListenDrops

Mon, 01 Jan 0001 00:00:00 +0000

Users report intermittent “connection refused” or timeouts. Nginx logs show 502s. uWSGI logs show nothing: no errors, no exceptions, no harakiri events. The master is alive, workers are accepting requests, throughput looks normal on average. But clients are being turned away.

The explanation is in two kernel counters that uWSGI cannot report on its own: TcpExtListenOverflows and TcpExtListenDrops. When all uWSGI workers are busy and the kernel’s accept queue (the listen backlog) fills, the kernel drops new connections before uWSGI’s accept() call ever runs. The application has no visibility into this event. The only evidence lives in /proc/net/netstat.

uWSGI Emperor healthy but vassal dead: monitoring each instance independently

Mon, 01 Jan 0001 00:00:00 +0000

The Emperor process is running, its stats endpoint responds, and it continues scanning config directories. But one application is down. Clients get connection refused or timeouts. Your monitoring says the Emperor is healthy because it is. Emperor liveness is not application liveness.

In Emperor mode, the Emperor manages one vassal (a full uWSGI instance) per config file. Each vassal is an independent process tree with its own master, workers, and stats server. The Emperor monitors config files and spawns or reloads vassals, but a vassal can die and fail to restart on a broken config while the Emperor runs unaffected. Vassal states:

uWSGI file descriptor limits: raising ulimit -n and systemd LimitNOFILE

Mon, 01 Jan 0001 00:00:00 +0000

The default per-process file descriptor limit on many Linux distributions is 1024. For a uWSGI instance running multiple workers, each holding connections, sockets, log files, and database handles, that ceiling is too low for production.

File descriptor exhaustion in uWSGI is silent. When the limit is hit, accept() and open() calls fail with EMFILE. New connections are rejected with no uWSGI-level error, no log entry, and no stats counter reflecting the problem. Clients see connection resets or timeouts. The master process stays alive. Worker status looks normal. The only evidence is at the OS level.

uWSGI harakiri death spiral: workers killed and respawned while throughput collapses

Mon, 01 Jan 0001 00:00:00 +0000

Workers are being killed by harakiri and respawned in a tight loop. Every request blocks past the configured timeout. The master sends SIGKILL to the worker, forks a replacement, and the new worker immediately accepts the next queued request, which also blocks. Throughput collapses to near zero while the worker pool appears “busy” at or near 100%.

This is the harakiri death spiral: a composite failure where the root cause is almost never uWSGI itself. A downstream dependency (database, external API, DNS resolver) has become unresponsive or unreachable. Every request that touches that dependency hangs. Harakiri is working as designed, killing stuck workers, but the recycling provides no relief because the next request is equally doomed.

uWSGI harakiri not configured: stuck workers with no timeout and no recovery

Mon, 01 Jan 0001 00:00:00 +0000

uWSGI workers are vanishing one at a time. The master process is alive, the stats server responds, and harakiri_count reads zero across every worker. By every metric you thought mattered, the service looks healthy. Then you notice that half the workers have been in busy status for the last ten minutes without processing a single new request. Requests are timing out at the proxy. The listen queue is filling. The application is effectively down, and nothing in uWSGI is attempting to recover it.

uWSGI HARAKIRI ON WORKER: requests killed for exceeding the timeout

Mon, 01 Jan 0001 00:00:00 +0000

HARAKIRI ON WORKER N (pid: XXXX, try: 1) !!!

You see it in the uWSGI error log, followed by the master reporting the worker died by signal 9. Your monitoring shows a spike in 502 or 504 responses from the reverse proxy. Something in the request path is hanging long enough to exceed the configured harakiri limit, and the master process is killing workers to prevent total pool exhaustion.

Harakiri is doing its job. It is not the problem. The problem is whatever is causing requests to run past the timeout.

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

uWSGI harakiri-verbose: finding the blocked syscall behind a timeout

Mon, 01 Jan 0001 00:00:00 +0000

When a uWSGI worker exceeds the harakiri timeout, the master kills it with SIGKILL and respawns a replacement. The default harakiri log line identifies which worker died and when, but not what the worker was doing when it got stuck. The request could be CPU-bound (a pathological regex, a tight loop), blocked on I/O (a database query that never returns), or deadlocked on an internal lock. Each requires a different fix.

uWSGI in gevent/async mode: why worker busy ratio stops meaning anything

Mon, 01 Jan 0001 00:00:00 +0000

Switching uWSGI from pre-fork to gevent mode lets a single worker multiplex dozens or hundreds of concurrent requests on an event loop. The tradeoff: the worker busy ratio, the primary capacity metric in pre-fork mode, becomes unreliable. A worker reports “busy” whenever its event loop is running, which is nearly always, regardless of actual request load.

Teams that keep alerting on busy ratio after switching to gevent either see perpetual 100% utilization alarms or, worse, silence while real problems go undetected. The cheaper_busyness algorithm has a known incompatibility with gevent that causes workers to spawn under load but never scale back down.

uWSGI listen backlog and net.core.somaxconn: sizing the connection queue

Mon, 01 Jan 0001 00:00:00 +0000

The connection backlog is the buffer between arriving TCP connections and your uWSGI workers. It is set by two independent values that must agree: uWSGI’s --listen option and the kernel’s net.core.somaxconn. The effective backlog is the smaller of the two. If either is too small, the queue fills during brief traffic spikes or downstream slowdowns, and the kernel starts dropping connections silently.

The defaults are both low. uWSGI ships with --listen 100. Linux kernels before 5.4 default net.core.somaxconn to 128; kernels 5.4 and later raised the default to 4096. On any service handling hundreds of requests per second, a 200-millisecond downstream hiccup fills a 100-slot queue in under a second. The result is intermittent client-side connection errors (timeouts or “connection refused”) with nothing in the uWSGI logs.

uWSGI listen queue full: the backlog overflow that drops connections silently

Mon, 01 Jan 0001 00:00:00 +0000

Clients report connection timeouts or resets. Your load balancer shows 502s or 504s on requests to the uWSGI backend. The uWSGI master is running, workers are alive, the stats server responds, and application logs show no errors. This is listen queue overflow: the kernel accept backlog on the uWSGI listening socket is full, and the kernel is silently dropping new connections before accept().

The listen queue is the kernel-level buffer between completed TCP handshakes and available workers. When all workers are busy and this buffer fills, the kernel silently drops incoming connections. No uWSGI log entry is written. No uWSGI error counter increments. The stats server runs in the master process and stays responsive during complete worker starvation, so health checks that query the stats endpoint still pass. Health check endpoints handled by workers may also pass if they are lightweight enough to be accepted between drops. Meanwhile, real users cannot connect.

uWSGI listen_queue always zero: why the stats field is broken on Linux

Mon, 01 Jan 0001 00:00:00 +0000

You open the uWSGI stats server JSON during a traffic spike. listen_queue reads 0. load reads 0. listen_queue_errors reads 0. But nginx is returning 502s, clients are seeing connection refused, and all workers are busy.

The fields do not measure what you think. On standard Linux, listen_queue is broken. load is identical to listen_queue (the source code has a TODO comment admitting this). listen_queue_errors is dead code that is never incremented. All three read 0 regardless of actual socket backlog pressure.

uWSGI master process dead: total outage while the PID file lingers

Mon, 01 Jan 0001 00:00:00 +0000

Nginx returns 502. The uWSGI PID file exists at its expected path, so monitoring reports the service as “up.” But nothing is serving traffic. The master process is dead, and the stale PID file is lying to you.

The master holds the listening socket, forks workers, enforces harakiri timeouts, handles graceful reloads, and serves the stats endpoint. When it dies, workers are gone. No connections are accepted. The outage is total.

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

uWSGI monitoring checklist: the signals every production app server needs

Mon, 01 Jan 0001 00:00:00 +0000

The stats server (enabled with --stats <socket>) exports a JSON document with worker state, request counters, memory usage, and error rates. This checklist organizes those signals by maturity level, from survival to expert. Each level assumes the previous one is in place.

uWSGI is in maintenance mode (bugfixes only, no new features), so the stats schema and signal semantics are stable. Three fields are not: listen_queue, load, and listen_queue_errors are broken or dead code on standard Linux. This checklist flags every unreliable field and points to the external measurement that works instead.

uWSGI monitoring maturity model: from survival to expert

Mon, 01 Jan 0001 00:00:00 +0000

A four-level progression for uWSGI monitoring, from bare liveness checks to deep signal correlation. The levels are cumulative: you cannot skip to Level 3 by tracking RSS growth trends while ignoring harakiri rate. Each tier closes a specific class of blind spot that the previous tier could not see.

The model assumes the uWSGI stats server is enabled with --stats <address>. Without it, every level above survival is unreachable. HTTP access to the stats server requires the additional --stats-http flag; otherwise use uwsgi --connect-and-read <addr> for TCP sockets or socat - UNIX-CONNECT:<path> for UNIX sockets.

uWSGI processes vs threads: sizing concurrency without wasting memory

Mon, 01 Jan 0001 00:00:00 +0000

The concurrency model you choose in uWSGI sets how many requests your server handles simultaneously, what that costs in memory, and what your monitoring signals mean once traffic arrives. Get it wrong and you either waste memory on idle processes or starve the kernel listen queue because you misread what “all workers busy” indicates.

uWSGI supports three concurrency models. Pre-fork gives you one request per worker process. Threaded gives you N requests per worker via threads. Async (gevent or asyncio) gives you many requests per worker via an event loop. Each has a different memory profile, a different CPU characteristic, and a different definition of “busy.”

uWSGI reload blackout: a broken deploy leaves zero workers running

Mon, 01 Jan 0001 00:00:00 +0000

You deployed new code to uWSGI. The graceful reload killed the old workers, but throughput is zero. The master process is alive. Every worker it forks dies before accepting a connection.

The reload mechanism worked. The new code cannot initialize. Workers crash during startup, the master respawns them, and they crash again. No worker stays alive long enough to serve a request.

The master process appears healthy. Process checks pass. The stats server responds to polling. If your health check only verifies the master PID or pings the stats endpoint, it reports green while 100% of requests are dropped at the kernel backlog.

uWSGI reload thundering herd: capacity drops to zero during a slow restart

Mon, 01 Jan 0001 00:00:00 +0000

You deploy a new version of your application. Seconds later, request throughput collapses to zero. Nginx returns 502s. The uWSGI master process is alive and the stats server responds, but no workers are accepting connections. Thirty seconds to several minutes later, throughput recovers. If this pattern aligns exactly with every deployment, you are hitting the reload thundering herd.

A standard uWSGI graceful reload kills all workers simultaneously, then forks replacements. If your application has a slow startup phase (heavy imports, ML model loading, cache warming, database connection pool initialization), there is a window where zero workers are ready to serve. The kernel listen queue fills with pending connections, overflows, and drops new connections silently. The first requests that land after workers recover hit cold caches and empty connection pools, making them abnormally slow.

uWSGI reload-on-rss vs evil-reload-on-rss: recycling workers on memory limits

Mon, 01 Jan 0001 00:00:00 +0000

Two uWSGI options recycle workers when their resident set size crosses a threshold: reload-on-rss and evil-reload-on-rss. Both produce the same effect on a monitoring dashboard. The respawn_count counter increments, RSS drops to baseline, a new worker is forked. The memory sawtooth looks healthy. From the master process perspective, the two are indistinguishable.

The difference is in what happens to the in-flight request when the kill occurs.

reload-on-rss is graceful. The master signals the worker to shut down. The worker finishes its current request, delivers the full response, and exits. The replacement worker picks up the next connection from the listen queue. No client sees anything unusual.

uWSGI respawn rate high: telling crashes apart from max-requests recycling

Mon, 01 Jan 0001 00:00:00 +0000

You see respawn_count climbing across your uWSGI workers. The question is whether workers are crashing or whether uWSGI is doing what you configured it to do.

respawn_count is a single monotonic counter per worker slot that increments for every reason a worker can die and come back: max-requests recycling, reload-on-rss memory recycling, harakiri timeout kills, segfaults, OOM kills, and manual kill -9. The raw number tells you workers are churning. It does not tell you why.

uWSGI response time climbing: rising avg_rt and where it comes from

Mon, 01 Jan 0001 00:00:00 +0000

When avg_rt climbs in the uWSGI stats server, the instinct is to look for slow application code. That is often right, but avg_rt is more nuanced than a simple average response time. Understanding what it actually measures is the difference between a fast diagnosis and a misleading rabbit hole.

avg_rt is an exponential moving average (EMA), not a cumulative average. When it climbs, something per-request is getting slower. The question is whether the cause is a downstream dependency (database pool exhaustion, slow external API), resource contention (CPU saturation, GC storms, GIL pressure in threaded Python), or cascading starvation (workers backing up because each request holds the worker longer). Correlating avg_rt with the worker busy ratio narrows this quickly.

uWSGI RSS vs VSZ: reading worker memory without being fooled by shared pages

Mon, 01 Jan 0001 00:00:00 +0000

You look at your uWSGI stats and see 8 workers each reporting 500 MB of RSS. The host has 4 GB of RAM. By the math, you should be deep into swap, but vmstat shows zero swap activity and response times are fine.

The gap is copy-on-write (COW) sharing. uWSGI’s default model loads the application once in the master process, then forks workers that inherit the master’s memory. Linux marks those inherited pages as shared and read-only. As long as workers do not write to them, the pages stay shared across all workers. But Linux RSS counts every shared page fully for every process that maps it. Sum worker RSS across 8 workers and you may overstate real memory consumption by 2-5x.

uWSGI spooler backlog: deferred tasks piling up on disk

Mon, 01 Jan 0001 00:00:00 +0000

The uWSGI spooler is an on-disk deferred-job queue. Application code serializes work units into files in a spool directory, and dedicated spooler processes consume them asynchronously. When producers enqueue work faster than the spooler drains it, or when the spooler crashes or stalls, files accumulate on disk. The backlog grows silently, deferred work latency increases, and in the worst case the disk fills or tasks are silently dropped.

A spooler backlog does not affect user-facing HTTP latency. Workers continue serving traffic. The degradation is in the deferred pipeline: emails arrive late, reports are stale, notifications lag. This makes the backlog easy to miss until background jobs stop running entirely.

uWSGI stats server unreachable: socket permissions and a stuck master

Mon, 01 Jan 0001 00:00:00 +0000

Your monitoring collector reports the uWSGI stats server as unreachable. Before debugging the stats server, answer one question: is uWSGI actually serving traffic?

The uWSGI stats server runs inside the master process and serves raw JSON over a socket (UNIX or TCP) when enabled with --stats. The master does not serve application requests. This separation matters: the stats server can be unreachable while every worker is processing traffic, and it can be reachable while every worker is stuck. Stats reachability and application availability are independent signals.

uWSGI stats server: enabling it and reading it without --stats-http

Mon, 01 Jan 0001 00:00:00 +0000

The uWSGI stats server is the primary data source for every monitoring signal in the uWSGI playbook: worker busy ratio, harakiri count, avg_rt, respawn rate, RSS, exception counts, and more. Without it, you are blind to internal state. With it, you have complete visibility into worker pool health, saturation, and failure modes.

The stats server must be explicitly enabled with the --stats option. It is not on by default. Once enabled, it serves a JSON document containing the full internal state of the master process and all workers, including PIDs, worker status, request counters, memory usage, and per-core request data.

uWSGI stats socket exposure: internal state leaking on a public port

Mon, 01 Jan 0001 00:00:00 +0000

The uWSGI stats server, enabled with --stats, serves a JSON blob containing the complete internal state of the master and all workers: PIDs, memory usage, request counts, response times, configuration details, and in-flight request data. When this socket is reachable from an untrusted network, every field in that JSON is an information-disclosure vector.

The stats server has no authentication. Access control is entirely network-level. Any client that can connect to the socket address receives the full dump with no challenge, no token, no ACL. The common pattern --stats :9191 (address with no IP specified) binds on every interface, which means the stats endpoint is open to anyone who can reach the host on that port.

uWSGI threaded mode and the GIL: why more threads don't add CPU parallelism

Mon, 01 Jan 0001 00:00:00 +0000

You doubled the thread count on each uWSGI worker, expecting throughput to scale with your multi-core box. CPU utilization barely moved. Response time did not improve. Memory looks fine. The queue still fills under load.

The cause is almost certainly the CPython Global Interpreter Lock. In threaded mode, a uWSGI worker runs N OS threads, but all N threads share a single GIL within that process. For CPU-bound Python code, only one thread executes bytecode at a time regardless of how many threads you configured. Adding threads helps with I/O-bound workloads, where threads can yield the GIL while waiting on network or disk, but it does nothing for computation-heavy request handlers.

uWSGI throughput drop: requests per second falling with traffic steady

Mon, 01 Jan 0001 00:00:00 +0000

Throughput in uWSGI is a derived metric: sum per-worker requests counters across all workers, then compute the delta between polling intervals. Anything that disrupts those counters or changes how fast workers complete requests shows up as a throughput trend.

Two caveats before you start:

Throughput can rise during failure. If the app starts returning 500s immediately without processing, requests-per-second goes up while useful throughput goes down. Always pair throughput with exception rate.

uWSGI thundering herd: accept() contention and the thunder-lock fix

Mon, 01 Jan 0001 00:00:00 +0000

You have a uWSGI deployment with multiple worker processes, and something does not add up. CPU usage is elevated. Workers toggle between idle and busy. But request throughput is low, response times are higher than expected, and adding more workers makes things worse instead of better. The system looks under load but is not actually doing much work.

This is the uWSGI thundering herd problem. When a new connection arrives on the shared listening socket, every idle worker process wakes up and races to call accept(). Only one wins. The rest burn CPU and kernel time on a context switch for nothing, then go back to sleep. Under low-to-moderate traffic with many workers, this contention consumes more CPU than the actual request processing.

uWSGI too many open files: file descriptor exhaustion and EMFILE

Mon, 01 Jan 0001 00:00:00 +0000

When the uWSGI process hits its file descriptor limit (RLIMIT_NOFILE), accept() and open() start returning EMFILE (errno 24). New connections are silently rejected. Logging fails. Application code throws exceptions that look like disk or network failures. The uWSGI stats endpoint does not report file descriptor usage, so there is no uWSGI-level signal pointing to the real problem. Operators typically chase disk space, I/O, or network connectivity before realizing the process has simply run out of file descriptors.

uWSGI worker exceptions climbing: unhandled errors reaching the WSGI layer

Mon, 01 Jan 0001 00:00:00 +0000

The workers[].exceptions counter is climbing, which means unhandled exceptions are propagating past your application code and reaching the uWSGI WSGI layer. Each increment typically corresponds to a 500 response delivered to the client. The counter is per-worker and monotonically increasing, so track the rate of change (delta over your polling interval), not the absolute value.

Critical nuance: this counter systematically undercounts application errors. If your framework (Django, Flask, FastAPI, and most others) catches exceptions via middleware and returns a 500 response itself, uWSGI never sees the exception. The request completes “successfully” from uWSGI’s perspective, and the counter does not increment. When the counter does climb, exceptions are escaping the framework entirely – a more severe condition than a framework-handled 500.

uWSGI worker killed by the OOM killer: mysterious respawns under memory pressure

Mon, 01 Jan 0001 00:00:00 +0000

You see worker respawns in the uWSGI log that do not match your max-requests cadence. The master reports workers dying from signal 9 (SIGKILL), and either harakiri is not configured or the harakiri count is zero. Workers come back, serve traffic for a while, then die again. The interval shrinks over time.

This is the signature of the Linux OOM killer targeting uWSGI workers. As total worker RSS grows beyond available RAM, the kernel swaps, performance degrades, and the OOM killer selects the largest process on the system. In a uWSGI deployment, that process is almost always a worker. The master respawns it, the new worker re-imports the application, RSS climbs back, and the cycle repeats.

uWSGI worker memory leak: RSS climbing across all workers

Mon, 01 Jan 0001 00:00:00 +0000

Per-worker RSS climbs steadily. All workers track each other in lockstep. After a restart, RSS looks stable for hours or days, then the pattern repeats. With max-requests or reload-on-rss configured, you see a sawtooth: RSS rises, a worker recycles, RSS drops, then rises again. Without those directives, workers eventually hit the OOM killer or start swapping.

The cause may be a genuine leak in application code, Python allocator fragmentation that never returns pages to the OS, a C extension bug, or Docker file-descriptor inflation. The first two are operationally identical: RSS grows monotonically and does not come back down without a process recycle.

uWSGI worker pool starvation: the silent outage where every worker is busy

Mon, 01 Jan 0001 00:00:00 +0000

Every worker shows status: "busy". The master process is alive. The stats server responds instantly. Your load balancer health check returns 200. But real users are seeing timeouts, connection refused errors, or hanging pages. This is worker pool starvation.

The mechanism is a concurrency cliff. uWSGI’s pre-fork model assigns one request per worker at a time in the default configuration. When every worker is occupied with a slow or hanging request, new connections pile into the kernel listen queue (socket backlog). Once that queue fills, the kernel silently drops connections with no uWSGI log entry, no error counter, and no exception. The service is dead for real traffic while every surface-level health signal stays green.

uWSGI worker respawn loop: 'DAMN ! worker died :( trying respawn'

Mon, 01 Jan 0001 00:00:00 +0000

The uWSGI master logs DAMN ! worker N (pid: XXX) died, killed by signal S :( trying respawn ... when it receives SIGCHLD for a worker that exited unexpectedly. The next line is typically Respawned uWSGI worker N (new pid: XXXX). In a respawn loop, these pairs repeat rapidly: the master forks a replacement, the replacement dies, and the cycle continues.

The signal number S is your primary diagnostic clue. Signal 9 (SIGKILL) means OOM kill or harakiri. Signal 11 (SIGSEGV) means a C extension crashed. Signal 6 (SIGABRT) means an assert failed. A worker that dies less than one second after spawn is hitting a startup failure, not a request-time problem.

uWSGI worker segfault: SIGSEGV in a C extension and the respawn that follows

Mon, 01 Jan 0001 00:00:00 +0000

A worker dies with signal 11. The master respawns it. The uWSGI log records DAMN ! worker N (pid: XXXX) died, killed by signal 11 :( trying respawn ... followed by Respawned uWSGI worker N (new pid: YYYY). From the outside, the service looks like it survived a momentary blip. It did not. A SIGSEGV means something in C-level code crashed: a compiled extension (numpy, lxml, a database driver, OpenSSL, protobuf), a uWSGI internal bug, or memory corruption. Python application code cannot normally produce SIGSEGV.

uWSGI worker stuck in busy: a hung request that never returns

Mon, 01 Jan 0001 00:00:00 +0000

One worker sits in busy far longer than any legitimate request should take. The others cycle through idle and busy normally. The stuck worker is not crashing, not erroring, and not completing. It is holding a request open indefinitely and will stay that way until something kills it.

This is the single-worker poisoning pattern. A specific request triggered a pathological code path: blocking I/O without a timeout, a regex catastrophe, an unbounded database query, or a deadlock in a C extension. The worker called accept(), began processing, and never returned. Its request counter is frozen. Its running_time stopped advancing. One slot of your worker pool is permanently consumed.

uWSGI write and read errors: broken pipes and clients that disconnect

Mon, 01 Jan 0001 00:00:00 +0000

write_errors and read_errors are per-core counters in the uWSGI stats server. write_errors increments when a socket write fails during response delivery, almost always because the client disconnected before the response finished (broken pipe). read_errors increments when the connection is lost during request body reading. Some of both are normal: users navigate away, mobile clients switch networks, browsers cancel pending requests. A sustained rise in write_errors, especially when correlated with rising response time or worker respawns, points to a real problem.