12 expert NGINX WebSocket Drops answers researched from official documentation. Every answer cites authoritative sources you can verify.
The proxy_read_timeout default is 60 seconds. Nginx closes connection if upstream server doesn't transmit data within this period. For WebSocket, idle connections are normal. Solution: Set proxy_read_timeout 7d; in location block for WebSocket endpoints. This gives 7-day timeout for long-lived connections. The 60-second drop is deterministic - always happens at that interval if no data sent. Affects all idle WebSocket connections behind nginx reverse proxy.
Essential config: proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 7d; proxy_buffering off; proxy_cache off;. Also need map directive: map $http_upgrade $connection_upgrade { default upgrade; '' close; }. The Upgrade and Connection headers enable WebSocket protocol switch. HTTP 1.1 required for upgrade mechanism. Buffering must be disabled for real-time data. 7-day timeout prevents idle connection drops.
Server-side: Send ping every 30 seconds. Pattern: const ws = new WebSocket.Server({port: 8080}); ws.on('connection', (client) => { const interval = setInterval(() => { if (client.readyState === WebSocket.OPEN) client.ping(); }, 30000); client.on('close', () => clearInterval(interval)); }). Browsers automatically respond with pong. This resets nginx proxy_read_timeout. 30-second interval chosen to stay well under 60-second default timeout. Ping frames are part of WebSocket spec, near-zero overhead.
Default proxy_set_header directives don't forward Upgrade and Connection headers. Nginx only forwards explicitly configured headers. Without these headers, backend receives regular HTTP request and rejects with 426 Upgrade Required. Solution: Add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection $connection_upgrade;. Also define map: map $http_upgrade $connection_upgrade { default upgrade; '' close; }. This mapping handles both WebSocket and regular HTTP on same location. Without map, all requests get Connection: upgrade breaking non-WebSocket traffic.
Yes, proxy_buffering off; is required for WebSocket. Buffering delays messages until buffer fills, breaking real-time communication. WebSocket needs immediate message forwarding in both directions. Pattern: location /ws { proxy_buffering off; proxy_cache off; }. Buffering off sends data to client immediately as received from upstream. Cache off prevents WebSocket responses from being cached. Without these, messages queue up causing delays and connection issues. Small performance impact but necessary for WebSocket functionality.
Enable debug logging: error_log /var/log/nginx/error.log debug;. Add custom log format capturing upstream timing: log_format ws_log '$remote_addr [$time_local] "$request" $status upstream: $upstream_addr upstream_response_time: $upstream_response_time request_time: $request_time'; access_log /var/log/nginx/ws.log ws_log;. Check logs for: proxy_read_timeout errors, upstream connection closed messages, 426 Upgrade Required responses. Common issues visible in logs: missing Upgrade header, timeout exactly at 60s (check proxy_read_timeout), backend not responding to ping. Debug mode adds overhead - disable after debugging.
The proxy_read_timeout default is 60 seconds. Nginx closes connection if upstream server doesn't transmit data within this period. For WebSocket, idle connections are normal. Solution: Set proxy_read_timeout 7d; in location block for WebSocket endpoints. This gives 7-day timeout for long-lived connections. The 60-second drop is deterministic - always happens at that interval if no data sent. Affects all idle WebSocket connections behind nginx reverse proxy.
Essential config: proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 7d; proxy_buffering off; proxy_cache off;. Also need map directive: map $http_upgrade $connection_upgrade { default upgrade; '' close; }. The Upgrade and Connection headers enable WebSocket protocol switch. HTTP 1.1 required for upgrade mechanism. Buffering must be disabled for real-time data. 7-day timeout prevents idle connection drops.
Server-side: Send ping every 30 seconds. Pattern: const ws = new WebSocket.Server({port: 8080}); ws.on('connection', (client) => { const interval = setInterval(() => { if (client.readyState === WebSocket.OPEN) client.ping(); }, 30000); client.on('close', () => clearInterval(interval)); }). Browsers automatically respond with pong. This resets nginx proxy_read_timeout. 30-second interval chosen to stay well under 60-second default timeout. Ping frames are part of WebSocket spec, near-zero overhead.
Default proxy_set_header directives don't forward Upgrade and Connection headers. Nginx only forwards explicitly configured headers. Without these headers, backend receives regular HTTP request and rejects with 426 Upgrade Required. Solution: Add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection $connection_upgrade;. Also define map: map $http_upgrade $connection_upgrade { default upgrade; '' close; }. This mapping handles both WebSocket and regular HTTP on same location. Without map, all requests get Connection: upgrade breaking non-WebSocket traffic.
Yes, proxy_buffering off; is required for WebSocket. Buffering delays messages until buffer fills, breaking real-time communication. WebSocket needs immediate message forwarding in both directions. Pattern: location /ws { proxy_buffering off; proxy_cache off; }. Buffering off sends data to client immediately as received from upstream. Cache off prevents WebSocket responses from being cached. Without these, messages queue up causing delays and connection issues. Small performance impact but necessary for WebSocket functionality.
Enable debug logging: error_log /var/log/nginx/error.log debug;. Add custom log format capturing upstream timing: log_format ws_log '$remote_addr [$time_local] "$request" $status upstream: $upstream_addr upstream_response_time: $upstream_response_time request_time: $request_time'; access_log /var/log/nginx/ws.log ws_log;. Check logs for: proxy_read_timeout errors, upstream connection closed messages, 426 Upgrade Required responses. Common issues visible in logs: missing Upgrade header, timeout exactly at 60s (check proxy_read_timeout), backend not responding to ping. Debug mode adds overhead - disable after debugging.