WebSockets behind nginx drop when the connection is idle
WebSocket closes with code 1006 after roughly 60 seconds of no messagesShort answer
nginx closes a proxied connection when the backend sends no data for 60 seconds, and a quiet WebSocket looks exactly like that. Raise proxy_read_timeout above your idle gap, or make the server send ping frames more often than that. Also confirm the Upgrade and Connection headers are passed.
Fix it fast
1Find out which cause you have
Note how long the socket lives before it drops, then check the timeout settings nginx applies to that location.
sudo nginx -T 2>/dev/null | grep -n "proxy_read_timeout\|proxy_send_timeout\|Upgrade"2Match what you see, then jump to its fix
- 1
The connection dies after about 60 seconds without trafficproxy_read_timeout is the 60 second defaultFix - 2
Raising the timeout only delays the drop, or a very long timeout is not acceptableThe server sends no keep-alive trafficFix - 3
Client logs transport close at a regular intervalSocket.IO heartbeat is longer than the proxy timeoutFix
- 1
What does the error look like?
WebSocket closes with code 1006 after roughly 60 seconds of no messagestransport close
Cause 1 of 3
proxy_read_timeout is the 60 second default
1Check
The default closes the connection when the proxied server sends nothing for 60 seconds. If nothing in the grep result sets it, the default applies.
sudo nginx -T 2>/dev/null | grep -n proxy_read_timeout2Fix
Set a value longer than the longest silence you expect, in the WebSocket location only.
location /ws/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
}3Verify
Reload nginx, open the socket and stay idle for more than 60 seconds.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
Cause 2 of 3
The server sends no keep-alive traffic
1Check
The docs name an alternative to a long timeout: the proxied server sends WebSocket ping frames regularly, and each one resets nginx's timer and shows whether the peer is alive.
grep -rn "ping" server.js src/ 2>/dev/null2Fix
Send a ping on an interval shorter than proxy_read_timeout. With the ws package that is a timer over the connected clients.
setInterval(() => {
wss.clients.forEach((client) => client.ping());
}, 30000);3Verify
Stay idle for two minutes; the connection stays open.
sudo tail -f /var/log/nginx/error.logConfirmed by nginx.org
Cause 3 of 3
Socket.IO heartbeat is longer than the proxy timeout
1Check
Socket.IO needs the proxy timeout to be bigger than pingInterval plus pingTimeout, which is 45 seconds by default. A shortened proxy timeout or a raised heartbeat breaks that.
grep -rn "pingInterval\|pingTimeout" src/ server.js 2>/dev/null2Fix
Make proxy_read_timeout larger than the sum.
# nginx: must exceed pingInterval + pingTimeout
proxy_read_timeout 120s;3Verify
Reload nginx and watch the client for a day of idle time; no transport close appears.
sudo nginx -t && sudo systemctl reload nginxConfirmed by socket.io
How do I stop it coming back?
- Set a heartbeat on the server instead of relying on a very large timeout.
- Give the WebSocket path its own location block so the long timeout does not apply to normal requests.
- Add a reconnect with backoff to the client, since any network can still drop a socket.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Servers
POST requests to a Node.js or Express API return 405 Not Allowed from nginx
The error page is served by nginx, and the Express logs show no request
When the 405 page comes from nginx and not from Express, nginx never handed the POST to your app.
3 causes, each with a fixServers
nginx 502 Bad Gateway in front of a Node.js app
connect() failed (111: Connection refused) while connecting to upstream
A 502 means nginx reached for your Node.js app and got nothing usable back.
5 causes, each with a fixServers
nginx gives up waiting for the app and returns 504
upstream timed out (110: Connection timed out) while reading response header from upstream
nginx returns 504 when the app behind it takes the request but sends nothing back within proxy_read_timeout (60 seconds by default), or when the connection cannot be opened in time.
5 causes, each with a fixServers
The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files
requests for your pages return 404 Not Found
The official nginx image serves whatever sits in /usr/share/nginx/html.
3 causes, each with a fixServers
Pages load unstyled because /_next/static files return 404 behind nginx
GET https://example.com/_next/static/chunks/main.js 404 (Not Found)
The browser asks for /_next/static/..
3 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fix