$ guides / uwsgi / uwsgi-connection-refused ▌

Operations Guides

uWSGI connection refused: clients turned away when the backlog overflows

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.

What this means

Every uWSGI listening socket has a kernel-managed accept queue, commonly called the listen backlog. New TCP connections complete their handshake and land in this queue. Workers pull connections from it via accept(). When every worker is busy and the backlog fills to its configured maximum, the kernel stops queuing new connections and drops them. The client sees connection refused.

The default listen backlog in uWSGI is 100 connections, set with --listen (short form -l). This value is set at the socket level via listen(), but the kernel caps it at net.core.somaxconn. On older Linux kernels, somaxconn defaults to 128. On newer kernels (5.4+) it defaults to 4096. Since uWSGI 2.0.10, on Linux, uWSGI refuses to start when --listen exceeds somaxconn (Listen queue size is greater than the system max net.core.somaxconn (N).); older releases let the kernel cap the backlog silently with no warning.

When the backlog overflows, uWSGI may log:

*** uWSGI listen queue of socket "ip:port" (fd: N) full !!! (101/100) ***

The first number is the current queue depth, the second is the configured maximum. This message is not guaranteed on every overflow event. The kernel drops connections silently, and the only definitive evidence is the TcpExtListenOverflows kernel counter or the Recv-Q column in ss output.

uWSGI’s own stats server cannot reliably report the listen queue depth on standard Linux. The listen_queue field relies on TCP_INFO behavior that varies across kernel versions, and the UNIX socket measurement requires a non-standard kernel ioctl. The load field is identical to listen_queue (not average latency, despite its name). The listen_queue_errors field exists in the JSON output but is never incremented in the source. All three are almost always 0 regardless of actual backlog state. Measure the queue externally via ss and nstat instead.

Common causes

Cause	What it looks like	First thing to check
Backlog overflow (workers saturated)	nginx 111 errors, all workers `busy`, throughput dropping	`ss -ltn` Recv-Q, worker busy ratio
somaxconn capping the backlog	uWSGI 2.0.10+ refuses to start with `Listen queue size is greater than the system max net.core.somaxconn (N).`	`cat /proc/sys/net/core/somaxconn`
Master process dead	No uwsgi master process, stats server unreachable, stale PID file	`kill -0 $(cat pidfile)`, `pgrep -f uwsgi`
Wrong socket path or permissions	nginx logs permission denied or cannot stat socket file	`ls -la /path/to/socket`, nginx error log
Reload failure (zero accepting workers)	Workers spawn and die immediately after SIGHUP, respawn_count climbing	Accepting worker count, application startup logs
Accept contention without thunder-lock	Workers mostly idle but throughput low, no backlog visible	Check for `thunder-lock` in config

Quick checks

# Check if the master process is alive
kill -0 $(cat /tmp/uwsgi.pid) 2>/dev/null && echo "alive" || echo "dead"

# Check the listen queue depth and configured backlog (TCP)
ss -ltn 'sport = :8000'

# Check kernel-level listen queue overflow counter
nstat -az TcpExtListenOverflows TcpExtListenDrops

# Check the effective somaxconn limit
cat /proc/sys/net/core/somaxconn

# Check the TCP SYN backlog limit
cat /proc/sys/net/ipv4/tcp_max_syn_backlog

# Check worker busy ratio from the stats server
uwsgi --connect-and-read 127.0.0.1:9191 | jq '([.workers[] | select(.status == "busy")] | length) as $busy | ([.workers[] | select(.pid > 0 and .status != "cheap")] | length) as $alive | if $alive > 0 then ($busy / $alive * 100 | floor) else 0 end'

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

# Search uWSGI logs for listen queue full messages
grep -r "listen queue" /var/log/uwsgi/

How to diagnose it

flowchart TD
    A["Connection refused or TCP RST"] --> B{"Master process alive?"}
    B -- No --> C["Dead listener: check OOM, crash, config"]
    B -- Yes --> D{"Socket visible in ss output?"}
    D -- No --> E["Wrong socket path or permissions"]
    D -- Yes --> F{"Any accepting workers?"}
    F -- No --> G["Reload failure or all workers cheaped"]
    F -- Yes --> H{"Busy ratio near 100%?"}
    H -- Yes --> I["Backlog overflow: workers saturated"]
    H -- No --> J["Check accept contention / thunder-lock"]

Verify the master is alive. Check the PID file with kill -0. If the master is dead, the issue is not backlog overflow. See uWSGI master process dead.
Verify the listening socket exists. Run ss -ltn 'sport = :PORT' for TCP or ss -lxn | grep uwsgi for UNIX sockets. If the socket is missing, uWSGI is not listening on the expected address. Check for a failed reload or wrong configuration.
Read the Recv-Q column. For a LISTEN socket, ss shows Recv-Q (current connections waiting in the accept queue) and Send-Q (the configured backlog). A sustained nonzero Recv-Q means workers cannot accept fast enough. If Recv-Q equals Send-Q, the backlog is full.
Check the kernel overflow counter. Run nstat -az TcpExtListenOverflows. This counter increments every time the kernel drops a connection because the accept queue was full. Any nonzero rate means connections are being actively dropped. Note: this counter is system-wide, so on multi-service hosts you need per-socket ss data to attribute drops to uWSGI.
Check worker saturation. Query the stats server for worker busy ratio and accepting worker count. If busy ratio is at or near 100%, the backlog is overflowing because workers are saturated. Identify which URIs are consuming workers.
Check somaxconn. Compare cat /proc/sys/net/core/somaxconn against your configured --listen value. If somaxconn is lower, uWSGI 2.0.10+ on Linux refuses to start with Listen queue size is greater than the system max net.core.somaxconn (N).; older releases let the kernel cap the backlog silently.
Rule out socket permission issues. For UNIX sockets, check ls -la /path/to/socket. The nginx worker user must have read/write access. Verify the socket path in nginx uwsgi_pass matches the actual socket path.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
Listen queue depth (`ss` Recv-Q on LISTEN socket)	Primary saturation indicator before drops occur	Sustained nonzero, or approaching Send-Q value
`TcpExtListenOverflows` (kernel counter)	Confirms connections are being dropped, system-wide	Any nonzero rate of change
Worker busy ratio	Explains why the queue is filling	Sustained above 80%, or reaching 100%
Accepting worker count	Detects dead or failed workers independent of busy ratio	Drops to zero while master is alive
`somaxconn` vs configured `--listen`	Effective backlog may be lower than configured	somaxconn less than `--listen` value
nginx upstream error rate	Client-visible symptom, lagging indicator	Spike in 502/504 or connection refused errors

Do not use the uWSGI stats fields listen_queue, load, and listen_queue_errors for alerting. They are unreliable on standard Linux. Use ss and kernel counters instead.

Fixes

Increase the backlog

If workers are briefly saturated during traffic bursts but recover quickly, increasing the backlog buys time for workers to catch up.

# uwsgi.ini
listen = 1024

Also raise the kernel limit. Note: appending to sysctl.conf repeatedly creates duplicate entries. Use a dedicated file under /etc/sysctl.d/ for service-specific settings:

# Add to a dedicated file to avoid duplicate entries
cat >> /etc/sysctl.d/99-uwsgi.conf << 'EOF'
net.core.somaxconn = 4096
net.ipv4.tcp_max_syn_backlog = 8192
EOF

# Apply immediately
sysctl -p /etc/sysctl.d/99-uwsgi.conf

Restart uWSGI after changing --listen. On Linux, keep --listen at or below somaxconn: since 2.0.10 uWSGI refuses to start when --listen exceeds it. A larger backlog absorbs transient spikes but does not fix sustained worker saturation. If workers are permanently overloaded, you need more workers or faster request processing.

Address worker saturation

If the busy ratio is sustained at 100%, the backlog is a symptom, not the cause. Workers cannot process requests fast enough.

Identify slow endpoints. Check workers[].uri in the stats JSON for busy workers. If all busy workers show the same URI, that endpoint is the bottleneck.
Check downstream dependencies. Database connection pool exhaustion, slow external API calls, and DNS resolution hangs are the most common causes of worker saturation.
Add workers. Increase --processes if CPU and memory headroom allow. Each worker is a full process copy.
Enable harakiri. Without harakiri, a single hung request permanently consumes a worker. Set --harakiri (in seconds) to 2-3x your expected maximum legitimate request duration. See harakiri timeout tuning.

Fix a dead listener

If the master process is gone, the fix is not backlog tuning. Check dmesg for OOM-killer evidence, check application logs for segfaults, and verify the startup configuration. See uWSGI master process dead.

For UNIX socket permission issues, ensure the nginx worker user has read/write access to the socket file. The --chmod-socket=660 directive sets permissions at startup.

Handle reload race conditions

A graceful reload (SIGHUP) kills all workers and respawns them. If the application has slow startup (heavy imports, model loading), there is a window with zero accepting workers where the backlog fills immediately.

Use --chain-reload to cycle workers one at a time instead of all simultaneously.
Verify new code with uwsgi --ini app.ini --no-server before reloading to catch import errors early.
During the reload window, the listen backlog is the only buffer. If it is too small, connections are dropped during every deployment.

Prevention

Monitor TcpExtListenOverflows. This kernel counter is the definitive signal that connections are being dropped. Alert on any nonzero rate of change. It is system-wide, so on multi-service hosts, correlate with per-socket ss data to attribute drops to uWSGI.
Set somaxconn above --listen. The kernel caps the backlog at somaxconn, and uWSGI 2.0.10+ on Linux refuses to start if --listen exceeds it. If you configure --listen 1024 but leave somaxconn at its default, raise somaxconn first.
Configure alarm-backlog. uWSGI can raise a named alarm when the listen queue is full. This requires the master process to be running.
```
alarm-backlog = myalarm
```
The alarm fires when the socket backlog queue fills. Pair it with an alarm handler (script, email, webhook) to get notified before clients see errors. The option was introduced in uWSGI 2.0.1.
Size the backlog for burst tolerance. A backlog of 100 connections at 500 req/s fills in 200ms. A backlog of 1024 buys 2 seconds of headroom during a downstream hiccup.
Do not use the stats server as a health check. The stats server is served by the master process and remains responsive during complete worker starvation. A health check must go through the worker pool to reflect real availability.
Use chain reload for deployments. This prevents the zero-capacity window that fills the backlog during every deployment.

How Netdata helps

Netdata collects kernel TCP/IP metrics including TcpExtListenOverflows and TcpExtListenDrops at per-second granularity, giving immediate visibility into connection drops that uWSGI’s own stats cannot report reliably.
The listen queue depth (Recv-Q on LISTEN sockets) is available through Netdata’s socket-level metrics, showing the gap between current queue depth and configured backlog without manual ss polling.
Netdata’s uWSGI collector reads the stats server JSON and surfaces worker busy ratio, accepting worker count, average response time, and harakiri count. Correlating worker saturation with kernel-level overflow counters confirms whether connection refusals are caused by backlog overflow or something else.
ML anomaly detection on the busy ratio and overflow counter rate can surface a filling backlog before it overflows, during the window where Recv-Q is climbing but drops have not yet started.
Per-second resolution matters because the listen queue can fill and overflow in under a second at high request rates. Ten-second polling intervals miss entire overflow events.