uWSGI stats server unreachable: socket permissions and a stuck master

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.

Most “stats unreachable” incidents fall into a small number of causes: --stats was never configured or was removed during a config change, the collector targets the wrong path or port, a UNIX socket has permission problems the collector cannot satisfy, or the master itself is stuck or dead.

Triage: stats down vs app down

The loss of visibility from a dead stats server is not itself evidence of an application outage. The stats server is a diagnostic channel served by the master process. Workers do not participate in serving it.

The critical triage question: does the master process respond, and can you reach the stats endpoint from a manual test on the same host? If the master PID is alive and workers are serving requests (verifiable via nginx access logs or the kernel socket queue), then the stats server has an access or configuration problem. If the master is dead, the application is down and the stats server went with it.

flowchart TD
    A["Stats collector reports unreachable"] --> B{"Master PID alive?"}
    B -- No --> C["Actual outage:
master dead or crashed"]
    B -- Yes --> D{"Stats socket or port exists?"}
    D -- No --> E["--stats not configured
or vacuum removed it"]
    D -- Yes --> F{"Manual connect works?"}
    F -- No --> G["Stale socket or
master stuck"]
    F -- Yes --> H{"Collector user can read?"}
    H -- Permission denied --> I["UNIX socket mode mismatch"]
    H -- Broken pipe --> J["Collector write bug on UDS"]
    H -- Yes --> K["Wrong path or port
in collector config"]

One subtle case: the master is alive (PID exists) but unresponsive. This can happen if the master is stuck in a signal handler or if shared memory corruption has affected the stats subsystem. This is rare but should be distinguished from a simple permission error.

Common causes

Quick checks

These are read-only and safe to run at any time.

# Master PID alive?
kill -0 $(cat /tmp/uwsgi.pid) 2>/dev/null && echo "alive" || echo "dead"

# Is --stats configured?
grep -ri stats /etc/uwsgi/

# Listening TCP sockets for stats
ss -ltnp | grep uwsgi

# Listening UNIX sockets for stats
ss -lxn | grep uwsgi

# Read stats from TCP socket (raw JSON, no --stats-http needed)
uwsgi --connect-and-read 127.0.0.1:1717 | python3 -c "import sys,json; d=json.load(sys.stdin); print('pid:', d['pid'])"

# Read stats from UNIX socket via socat
socat - UNIX-CONNECT:/tmp/uwsgi-stats.sock | python3 -c "import sys,json; d=json.load(sys.stdin); print('pid:', d['pid'])"

# UNIX socket permissions
ls -la /tmp/uwsgi-stats.sock

# HTTP stats (only works if --stats-http is enabled)
curl --max-time 2 http://127.0.0.1:1717/ | head -c 200

# OOM killer activity
dmesg | grep -i "killed process" | tail -5

How to diagnose it

1. Is the master PID alive? If kill -0 fails, you have an actual outage, not a monitoring problem. Check dmesg for OOM kills or segfaults. If the PID file is stale (process gone but file remains), the master was killed without cleanup.

2. Is --stats configured at all? Search the uWSGI configuration files for the stats directive. If absent, stats-based monitoring has never worked or broke after a config change. The stats server must be explicitly enabled.

3. What address is the stats server bound to? --stats accepts a TCP address (127.0.0.1:1717), a UNIX socket path (/tmp/uwsgi-stats.sock), or an abstract socket (@foobar). Use ss -ltn for TCP and ss -lxn for UNIX sockets to find what is actually listening.

4. Can you connect manually as the uWSGI user? Use uwsgi --connect-and-read <addr> for TCP or socat - UNIX-CONNECT:<path> for UNIX sockets. If this works, the stats server is up and the problem is in collector access or configuration. If it fails, the master may be stuck.

5. Can the collector user connect? If the collector runs as a different user (for example, netdata), test with sudo -u netdata socat - UNIX-CONNECT:/path/to/stats.sock. Permission denied confirms a UNIX socket permission mismatch.

6. Is the collector hitting a UDS write bug? If the collector uses a UNIX domain socket and fails with “write: broken pipe,” it may be sending data before reading. The uWSGI stats socket does not read input. This is a known incompatibility with some collectors. The workaround is a TCP stats socket on localhost.

7. Is this blind monitoring or an actual outage? If the master is alive, workers are serving (check nginx access logs or ss for active connections on the app port), but stats is unreachable, you have blind monitoring. The application is fine. Fix the stats access problem.

Metrics and signals to monitor

Fixes

--stats not configured or removed

Add the stats directive to the uWSGI configuration. For a TCP socket bound to localhost:

stats = 127.0.0.1:1717

For a UNIX socket:

stats = /tmp/uwsgi-stats.sock

If you need HTTP access (for curl), also add:

stats-http = true

After changing configuration, reload uWSGI and verify with uwsgi --connect-and-read.

Wrong path or port in collector

Compare the collector configured address against the actual bind target from ss. The most common mismatch is a path change (a deployment moved the socket to a different directory) or a port change. Update the collector configuration to match.

If you recently switched from UNIX socket to TCP (or vice versa) without updating the collector, this is the first thing to check.

UNIX socket permission mismatch

The stats UNIX socket inherits permissions from the process umask. chmod-socket is applied at bind time to every UNIX socket uWSGI creates through bind_to_unix, the stats socket included, so you can use it to widen access; there is no separate per-socket permission option.

The stats socket typically gets mode 0755 by default (umask 0022), which allows only the owner to connect. A collector running as a different user gets permission denied. Options:

• Set umask before starting uWSGI. umask 0007 produces sockets with mode 0770 (group access). umask 0077 produces 0700 (owner only). In systemd, use the UMask= directive in the unit file.
• Put the socket in a directory with group-based permissions. Create a directory owned by the uWSGI group, with the collector user added to that group. Socket access is then controlled by directory traversal permissions.
• Switch to TCP on localhost. stats = 127.0.0.1:1717 avoids socket permission issues entirely. This is the simplest fix for collectors that run as a different user.

Tradeoff: TCP on localhost is simpler for access control but exposes stats to any local process. UNIX sockets with directory-level permissions offer tighter control.

Stale socket file

If the master crashed without cleanup, the old UNIX socket file may persist on disk. A new master cannot bind to the same path until the stale file is removed.

The vacuum = true option removes the stats socket on clean shutdown. If the master was killed by OOM or SEGV, vacuum does not run.

Fix: remove the stale socket file manually, then restart uWSGI.

# WARNING: confirm the master is NOT running first.
rm /tmp/uwsgi-stats.sock

Enable vacuum = true for future clean shutdowns.

Collector protocol mismatch on UDS

Some monitoring collectors write data to the stats socket before reading. The uWSGI stats server does not read input from the stats socket, so the write triggers a broken pipe (SIGPIPE) on the collector side.

The simplest fix is to switch to a TCP stats socket on localhost. TCP sockets do not exhibit this write-before-read incompatibility.

If you must use a UNIX socket, an alternative is to place a socat relay in front of the stats socket that absorbs the write:

socat TCP-LISTEN:1717,fork UNIX-CONNECT:/tmp/uwsgi-stats.sock

This exposes the UNIX stats socket on localhost TCP port 1717 so the collector talks to socat instead of uWSGI (socat relays both directions; TCP-LISTEN, UNIX-CONNECT, and fork are documented socat address types/options). This adds complexity and a process to manage.

Master stuck or dead

If kill -0 on the master PID succeeds but the master does not respond to signals or serve stats, the master may be stuck in a signal handler or experiencing shared memory corruption. This is rare.

In uWSGI 2.0.x, SIGTERM triggers a brutal reload by default (SIGHUP a graceful reload, and SIGINT/SIGQUIT an immediate shutdown of the whole stack). Set die-on-term = true (functional through 2.0.28; deprecated in newer master builds) to make SIGTERM behave as shutdown. Sending the wrong signal to a stuck master can worsen the situation.

If the master is dead:

1. Check dmesg for OOM kills or segfaults.
2. Check available disk space. A full filesystem prevents pidfile writes and socket creation.
3. Check uWSGI logs for backtraces or “SIGSEGV” / “SIGABRT” on the master.
4. Restart uWSGI and monitor for recurrence.

Prevention

• Bind stats to localhost or a UNIX socket. Never bind --stats to 0.0.0.0 or a bare port like :9191 (which binds all interfaces). The stats JSON contains PIDs, URIs, configuration details, and in-flight request data. There is no authentication on the stats server.
• Use TCP on localhost for mixed-user environments. If the collector runs as a different user than uWSGI, a TCP socket on 127.0.0.1 sidesteps permission issues entirely.
• Enable vacuum = true. Cleans up UNIX socket files on clean shutdown and prevents stale sockets from blocking restarts.
• Monitor stats reachability independently from master liveness. A process check on the master PID tells you the process exists. A stats collection check tells you the diagnostic channel works. These are different failure modes.
• Track collector success rate. Alert on collector failure itself, not on stale or flatlined metrics. A dashboard showing the last known values is not the same as a healthy monitoring pipeline.
• Set umask explicitly. If using a UNIX stats socket, set the umask in the service definition (systemd UMask= or a wrapper script) so socket permissions are predictable across restarts.

How Netdata helps

• Master process liveness is tracked separately from stats collection. When the stats collector fails, Netdata still shows whether the master process is alive, so you can distinguish blind monitoring from an actual outage.
• Per-second collection timestamps the exact moment stats goes unreachable. The transition from collecting to failing is visible, not hidden in a polling gap.
• Host-level signals remain visible when stats is dark. CPU, memory, network connections, and disk I/O are collected independently of the uWSGI stats server, giving a fallback view of whether the service is still doing work.
• Collector health is observable. Netdata tracks its own collector success and failure rates, so you can alert on “collector stopped working” rather than waiting for someone to notice a flatlined dashboard.

Related guides

• uWSGI all workers busy: reading the busy ratio before the queue fills
• uWSGI avg_rt is not a real average: why the latency number lies
• uWSGI cache subsystem: hit ratio drops and ‘full’ insert failures
• uWSGI capacity planning: the leading indicators before saturation
• uWSGI chain reload: cycling workers one at a time for zero-downtime deploys
• uWSGI cheaper subsystem: dynamic worker scaling and the false ‘missing workers’ alert
• uWSGI connection pool cascade: downstream latency that stalls every worker
• uWSGI connection refused: clients turned away when the backlog overflows
• uWSGI Emperor healthy but vassal dead: monitoring each instance independently
• uWSGI file descriptor limits: raising ulimit -n and systemd LimitNOFILE
• uWSGI in gevent/async mode: why worker busy ratio stops meaning anything
• uWSGI threaded mode and the GIL: why more threads don’t add CPU parallelism