WebSocket connection to ws://localhost:3000/ws failed for a React dev server behind nginx or Docker
WebSocket connection to 'ws://localhost:3000/ws' failedShort 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.
Fix it fast
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/ws2Match what you see, then jump to its fix
- 1
The request never upgrades: there is no 101 Switching Protocols responsenginx does not pass the Upgrade headersFix - 2
The WebSocket works at first, then drops about a minute laterThe connection closes after 60 seconds of silenceFix - 3
The 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
The dev server refuses requests that arrive under a hostname it does not knowThe host header is rejectedFix
- 1
What does the error look like?
WebSocket connection to 'ws://localhost:3000/ws' failedHot reload does not work behind a proxyThe 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 reloadConfirmed by nginx.org
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 reloadConfirmed by nginx.org
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.js2Fix
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 filterConfirmed by webpack.js.org
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.js2Fix
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.comConfirmed by webpack.js.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
Related fixes
Web apps
React dev server in Docker does not reload when you save a file
Changes appear only after docker compose restart or a rebuild
File-change events often do not cross from your host into a container, so the dev server never notices the edit.
3 causes, each with a fixWeb apps
The browser refuses a ws:// connection opened from your HTTPS React app
Failed to construct 'WebSocket': An insecure WebSocket connection may not be initiated from a page loaded over HTTPS.
Your page is on HTTPS but the socket URL starts with ws://, and browsers refuse that mix.
4 causes, each with a fixWeb apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fix