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 . This value is set at the socket level via listen(), but the kernel silently caps it at net.core.somaxconn. On older Linux kernels, somaxconn defaults to 128. On newer kernels (5.4+) it defaults to 4096. If you set --listen 1024 but somaxconn is 128, the effective backlog is 128. uWSGI logs a warning at startup when this happens.

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 reportedly 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

CauseWhat it looks likeFirst thing to check
Backlog overflow (workers saturated)nginx 111 errors, all workers busy, throughput droppingss -ltn Recv-Q, worker busy ratio
somaxconn capping the backloguWSGI warns “listen backlog limited to N connections” at startupcat /proc/sys/net/core/somaxconn
Master process deadNo uwsgi master process, stats server unreachable, stale PID filekill -0 $(cat pidfile), pgrep -f uwsgi
Wrong socket path or permissionsnginx logs permission denied or cannot stat socket filels -la /path/to/socket, nginx error log
Reload failure (zero accepting workers)Workers spawn and die immediately after SIGHUP, respawn_count climbingAccepting worker count, application startup logs
Accept contention without thunder-lockWorkers mostly idle but throughput low, no backlog visibleCheck 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"]

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. Check somaxconn. Compare cat /proc/sys/net/core/somaxconn against your configured --listen value. If somaxconn is lower, the effective backlog is capped silently. uWSGI logs this at startup.

  7. 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

SignalWhy it mattersWarning sign
Listen queue depth (ss Recv-Q on LISTEN socket)Primary saturation indicator before drops occurSustained nonzero, or approaching Send-Q value
TcpExtListenOverflows (kernel counter)Confirms connections are being dropped, system-wideAny nonzero rate of change
Worker busy ratioExplains why the queue is fillingSustained above 80%, or reaching 100%
Accepting worker countDetects dead or failed workers independent of busy ratioDrops to zero while master is alive
somaxconn vs configured --listenEffective backlog may be lower than configuredsomaxconn less than --listen value
nginx upstream error rateClient-visible symptom, lagging indicatorSpike 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. The effective backlog is min(--listen, somaxconn). 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 silently caps the backlog. If you configure --listen 1024 but leave somaxconn at its default, the effective backlog may be far lower than intended.
  • 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.
  • 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.