An nginx error log fills with "768 worker_connections are not enough". What do the `worker_processes` and `worker_connections` directives control, how do they combine into a capacity ceiling, and why does a reverse-proxy workload hit that ceiling sooner than a static-file one?

## What the two directives actually mean nginx runs one master process and several workers. The master reads configuration, binds listening sockets and manages workers; the workers do all the connection handling, each in a single-threaded event loop. - **`worker_processes`** (main context) sets how many workers exist. `worker_processes auto;` — supported since nginx 1.2.5 — sets it to the number of CPU cores detected, which is the right default for a CPU-bound event loop. - **`worker_connections`** (events context) caps how many simultaneous connections *one worker* may hold. The nginx default is 512; several distribution packages ship 768 or 1024, which is where the number in that error message usually comes from. The key misreading is treating `worker_connections` as throughput. It is a concurrency limit — a count of open connections at one instant — and it includes everything the worker holds: active client connections, idle keep-alive client connections waiting for another request, connections to upstream servers, and connections nginx opens for its own purposes. ## The capacity arithmetic The absolute ceiling is: ``` max simultaneous connections = worker_processes × worker_connections ``` With 4 workers at 768 that is 3,072 connections in total — but connections are not clients. For a **static file server**, each client connection uses one slot, so the ceiling is roughly the client ceiling. Keep-alive already inflates it, because an idle connection a browser is holding open still occupies a slot even though no request is in flight. For a **reverse proxy**, each proxied request needs a client-side connection *and* a connection to the upstream, and both are charged to the same worker's budget. The practical client ceiling is therefore about half the product. Enabling `keepalive` in the `upstream` block reduces how often those upstream connections are created, but pooled connections still occupy slots while they are held. ## Reading the error correctly `768 worker_connections are not enough` means a worker hit its limit and could not take on more. Symptoms at the client are hangs, resets and connections that never get a response, while nginx's CPU and the application's own logs look unremarkable — nginx never got far enough to log much per request. Before raising the number, ask *why* so many connections are open at once. By Little's law, concurrency is arrival rate times how long each connection is held. A ceiling reached at modest traffic usually means connections are being held far too long, and the honest causes are: - **Slow upstreams.** If backend latency climbs from 50 ms to 5 s, concurrency rises a hundredfold at the same request rate. Raising the connection limit here just lets nginx queue more of a backlog it cannot clear. - **Long keep-alive with many idle clients.** A generous `keepalive_timeout` and a large client population means a large idle population holding slots. - **Long-lived connections by design** — WebSocket upgrades, server-sent events, streaming downloads — where high concurrency is normal and the limit genuinely needs to be sized for it. ## Raising it safely When the concurrency is legitimate, raise `worker_connections` — values in the tens of thousands are ordinary for a proxy — and raise `worker_rlimit_nofile` (main context) alongside it, because every connection and every open file consumes a file descriptor, and the per-worker descriptor limit must comfortably exceed `worker_connections` to leave room for upstream sockets, log files and cached file handles. A configuration that raises connections but not descriptors trades one error message for another. `worker_rlimit_nofile` sets the limit nginx requests for its worker processes; the value the operating system is willing to grant is a separate, host-level concern. Also reconsider `worker_processes`: on a machine where nginx is one tenant among several, pinning workers to fewer than the core count is sometimes right, and it lowers total capacity proportionally, so the two numbers must be chosen together. ```nginx worker_processes auto; worker_rlimit_nofile 65535; events { worker_connections 16384; } ``` And instrument it: the stub status module exposes the live active-connection count, so you can watch headroom against the configured ceiling instead of rediscovering it from the error log.