NGINX WebSocket Proxying: From Handshake to Idle Timeout
A page can load while its WebSocket fails. Separate handshake errors from idle disconnects, configure the upgrade route, and verify the real client in staging.
DM
Imagine a small operations board. This is a hypothetical example: the page loads, people can sign in, but the live updates never arrive. Or they work briefly, then stop when the board goes quiet. Those symptoms can look similar from a desk. They ask different questions at the proxy.
For NGINX WebSocket proxying, first establish whether the opening handshake succeeds. Only investigate an idle timeout after the real client has established a connection. Forward the upgrade headers on the correct route, verify an application message, then examine periods with no upstream data. Increasing a timeout cannot repair a failed upgrade.
This guide covers the HTTP/1.1 Upgrade path on self-managed NGINX. It does not cover HTTP/2 extended CONNECT. The snippets are illustrative configuration fragments, not a tested deployment or a complete TLS server.
Find the point where the connection stops
Open the application's actual WebSocket client and its network or frame inspector. Record the exact wss:// URL, handshake result and whether a legitimate application message arrives. Keep credentials out of screenshots and shared logs. Check the upstream route and the application's required authentication, Origin and subprotocol settings.
A normal page request proves that ordinary HTTP can work. It does not exercise the WebSocket opening exchange. Under RFC 6455's opening-handshake rules, the client must validate the response, including Sec-WebSocket-Accept and any negotiated protocol details. Seeing 101 Switching Protocols in a log is useful evidence; a client accepting that handshake and receiving an application message is a stronger checkpoint.
If the endpoint returns an ordinary 200, inspect whether the request reached the intended WebSocket handler. A 401 or 403 needs an authentication or policy investigation; do not disable Origin checks to make the symptom disappear. For a 502, use the separate NGINX ingress, proxy and application tracing guide before treating this as an idle problem.
Give the upgrade an explicit route
NGINX's WebSocket documentation explains the mechanism: Upgrade and Connection are hop-by-hop headers, so a reverse proxy must explicitly pass the needed values upstream. Its tunnel mode requires the client's upgrade request and the upstream's switching response.
For this example only, assume the application really serves /socket/ on port 3000 in the same host network namespace as NGINX. If it runs in another container or host, 127.0.0.1 may point somewhere else. Choose the upstream address from your deployment, not from this example.
Place this map inside the existing http {} context, alongside other maps if present. It does not belong inside a server or location block.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}Place the route inside the intended existing server {} context. Retain its TLS, access controls and application-specific requirements; this fragment does not define them.
location /socket/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}There is deliberately no URI suffix after the upstream address in proxy_pass. For this ordinary, unrewritten location, the original path goes upstream. Rewrites and other proxy_pass forms have different rules; check the directive documentation before adapting an existing route.
The explicit HTTP version makes this fragment clear across versions. Do not diagnose every installation as defaulting to HTTP/1.0: current NGINX documentation says the proxy default became HTTP/1.1 in 1.29.7; earlier versions defaulted to 1.0.
In staging, check the deployed binary's version and validate the intended configuration with nginx -v and nginx -t. If your deployment selects a custom configuration, use that same selection. The command reference says -t checks syntax and attempts to open referenced files. It does not reload NGINX or prove the WebSocket works. Apply changes through your normal staging reload process, then reconnect with the real client.
When it opens, investigate the quiet period
Now return to the board that works until nobody touches it. Note the last upstream frame and the close time. Compare that gap with the effective NGINX configuration and every outer proxy or load balancer on the path. A repeatable interval is a clue, not proof that a particular hop closed the connection.
proxy_read_timeout defaults to 60 seconds and measures the interval between successive upstream reads, not the total lifetime of the connection. An inherited override may change it. Client activity alone should not be your evidence that NGINX received upstream data.
NGINX documents two approaches for upstream silence: adjust the read timeout to the workload, or have the upstream send WebSocket Ping frames to reset it. Choose the application's documented server heartbeat where supported. Protocol Ping/Pong frames are defined in RFC 6455 section 5.5; an invented JSON “ping” message is not automatically that protocol mechanism.
Avoid choosing an hour-long timeout simply because another example uses one. Write down the intended quiet interval, the heartbeat behavior and the limits of the other hops. A longer proxy timer cannot override an outer service's shorter limit.
Leave staging with evidence you can use
Run one short acceptance exercise: connect with the production-shaped client and its legitimate credentials, exchange a real application message, then leave it quiet for the intended idle window. Observe heartbeat or other upstream frames and any close event. Finally, reconnect and check the application's recovery behavior, including whether it needs to reload missed state. A working tunnel does not define that recovery protocol.
That gives the board's operator a concrete next action. A rejected opening exchange sends you back to routing, headers or application policy. A validated connection that later closes sends you to upstream activity and the timeout chain. Keep those observations separate, and each configuration change has a reason.
Build the staging path on Cube
For a self-managed Linux workload, use Cube to build and verify your NGINX and application configuration. Confirm WebSocket support and timeout limits for any public ingress service you place in front of it.
Creation context: this article and its cover were created with AI assistance. The board scenario is hypothetical; the configuration and acceptance exercise were not executed against a customer workload. Technical statements were checked against the linked primary documentation.




