Why does a WebSocket connection fail through Nginx?

Question

IT Interview Practice · Accepted Answer

First distinguish a failed connection handshake from a connection that opens and later closes. The two symptoms lead to different checks.

## Let the application receive the upgrade request

For a dedicated WebSocket route, place this inside `server`:

```nginx
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 "upgrade";
}
```

`proxy_http_version` explicitly uses HTTP/1.1 toward the backend. `Upgrade` passes the client's requested protocol change. `Connection` tells the backend this connection is requesting that change. These headers need explicit forwarding because proxies do not simply pass every connection-specific header onward.

## Read the outcome

A successful handshake returns `101 Switching Protocols`. If you receive 404, check the backend path; if authentication fails, inspect application policy. The proxy configuration does not replace authentication or allowed-origin checks.

If the connection opens but closes after inactivity, inspect idle timeouts across Nginx and other proxies. Use server-sent WebSocket ping frames and an appropriate `proxy_read_timeout` together with client reconnect behavior. Increasing the timeout alone can keep dead connections around longer.

[Official documentation](https://nginx.org/en/docs/http/websocket.html).

Let the application receive the upgrade request

Read the outcome

Related questions