Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

WebSocket connection to ws://localhost:3000/ws failed for a React dev server behind nginx or Docker

ErrorWebSocket connection to 'ws://localhost:3000/ws' failed

Short answer

The dev server's hot reload opens a WebSocket on /ws. It fails when nginx does not pass the Upgrade headers, when the connection sits idle past nginx's 60 second read timeout, or when the browser is told the wrong host and port. Fix the proxy first, then the client URL.

  • Applies to nginx 1.27, webpack-dev-server 5, Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser network tab, filter by WS, and look at the status of the /ws request. A successful upgrade shows status 101.

    curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" http://localhost:3000/ws
  2. 2Match what you see, then jump to its fix

    1. 1The request never upgrades: there is no 101 Switching Protocols responsenginx does not pass the Upgrade headersFix
    2. 2The WebSocket works at first, then drops about a minute laterThe connection closes after 60 seconds of silenceFix
    3. 3The failed URL names a host or port that is not the one users open, for example localhost:3000 inside a containerThe browser is told the wrong host, port or pathFix
    4. 4The dev server refuses requests that arrive under a hostname it does not knowThe host header is rejectedFix

What does the error look like?

  • WebSocket connection to 'ws://localhost:3000/ws' failed
  • Hot reload does not work behind a proxy
  • The page loads but the console fills with failed WebSocket attempts

Cause 1 of 4

nginx does not pass the Upgrade headers

1Check

Upgrade and Connection are hop by hop headers, so nginx does not forward them unless told to.

grep -rn "Upgrade" /etc/nginx/

2Fix

Pass both headers explicitly in the location that proxies the dev server. Use HTTP 1.1 to the upstream on nginx versions before 1.29.7.

location / {
    proxy_pass http://app:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

3Verify

Test the config, reload nginx and repeat the curl check; the status should be 101.

sudo nginx -t && sudo nginx -s reload

Confirmed by nginx.org

Did this fix it?

Cause 2 of 4

The connection closes after 60 seconds of silence

1Check

nginx closes the connection if the proxied server sends nothing within 60 seconds by default.

grep -rn "proxy_read_timeout" /etc/nginx/

2Fix

Raise proxy_read_timeout in that location, or have the server send periodic ping frames.

proxy_read_timeout 1h;

3Verify

Keep the page open for several minutes and check the WS entry stays open.

sudo nginx -t && sudo nginx -s reload

Confirmed by nginx.org

Did this fix it?

Cause 3 of 4

The browser is told the wrong host, port or path

1Check

In a container, the dev server believes it runs on its own port, not on the proxy's public one.

grep -rn "webSocketURL\|client" webpack.config.js

2Fix

Tell the dev server client which address to use. Setting auto lets the browser use the address it loaded the page from.

// webpack.config.js
devServer: {
  client: {
    webSocketURL: 'auto://0.0.0.0:0/ws',
  },
}

3Verify

Reload the page and check the WS request URL in the network tab.

# browser network tab, WS filter

Confirmed by webpack.js.org

Did this fix it?

Cause 4 of 4

The host header is rejected

1Check

devServer.allowedHosts controls which hostnames are accepted. With auto it allows localhost, the host and the client URL hostname.

grep -rn "allowedHosts" webpack.config.js

2Fix

List the hostname users open in allowedHosts. Avoid all, because skipping the check exposes the dev server to DNS rebinding.

devServer: {
  allowedHosts: ['.example.com'],
}

3Verify

Open the app under that hostname.

curl -I http://app.example.com

Confirmed by webpack.js.org

Did this fix it?

How do I stop it coming back?

  • Proxy a dev server only for local work; serve a production build behind nginx instead.
  • Keep the Upgrade headers in a shared snippet reused by every WebSocket location.
  • Write the public host and port in one config file so the client URL is not guessed.

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

Next step

Want this handled for good?

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