Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

WebSockets behind nginx drop when the connection is idle

ErrorWebSocket closes with code 1006 after roughly 60 seconds of no messages

Short 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.

  • Applies to nginx 1.26, Node.js 22, Socket.IO 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The connection dies after about 60 seconds without trafficproxy_read_timeout is the 60 second defaultFix
    2. 2Raising the timeout only delays the drop, or a very long timeout is not acceptableThe server sends no keep-alive trafficFix
    3. 3Client logs transport close at a regular intervalSocket.IO heartbeat is longer than the proxy timeoutFix

What does the error look like?

  • WebSocket closes with code 1006 after roughly 60 seconds of no messages
  • transport 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_timeout

2Fix

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 nginx

Confirmed by nginx.org

Did this fix it?

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/null

2Fix

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.log

Confirmed by nginx.org

Did this fix it?

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/null

2Fix

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 nginx

Confirmed by socket.io

Did this fix it?

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:

Related fixes

Servers

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.