WebSocket to /_next/webpack-hmr fails when the Next.js dev server is behind nginx
WebSocket connection to 'ws://localhost/_next/webpack-hmr' failed: WebSocket is closed before the connection is establishedShort answer
Hot reload uses a WebSocket, and nginx does not forward the Upgrade and Connection headers unless you tell it to. Add both with proxy_set_header, set proxy_http_version 1.1 on nginx older than 1.29.7, and add the public hostname to allowedDevOrigins if you open the dev server through a name other than localhost.
Fix it fast
1Find out which cause you have
Send a WebSocket handshake through nginx. A working setup answers 101 Switching Protocols; anything else shows which hop breaks it.
curl -i -N http://localhost/_next/webpack-hmr \ -H "Connection: Upgrade" -H "Upgrade: websocket" \ -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ=="2Match what you see, then jump to its fix
- 1
The handshake does not return 101 Switching Protocolsnginx does not pass the Upgrade and Connection headersFix - 2
Headers are set as above, but the handshake still does not return 101nginx older than 1.29.7 proxies with HTTP/1.0Fix - 3
You browse to a name like dev.example.com or a tunnel host, not localhost, and the proxy headers are already correctThe dev server rejects the hostname you open it throughFix
- 1
What does the error look like?
WebSocket connection to 'ws://localhost/_next/webpack-hmr' failed: WebSocket is closed before the connection is established
Cause 1 of 3
nginx does not pass the Upgrade and Connection headers
1Check
Upgrade and Connection are hop-by-hop headers, so nginx does not forward them from the client to the proxied server on its own. Look at the location that proxies to the dev server.
grep -R -n -B2 -A6 "proxy_pass" /etc/nginx/sites-enabled/2Fix
Pass both headers explicitly. The map form keeps normal requests working when no Upgrade header is sent.
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
}3Verify
Test, reload and repeat the handshake.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
Cause 2 of 3
nginx older than 1.29.7 proxies with HTTP/1.0
1Check
The nginx WebSocket page marks proxy_http_version 1.1 as needed before version 1.29.7.
nginx -v2Fix
Add the directive in the same location block.
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}3Verify
Reload nginx and look for 101 in the handshake.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
Cause 3 of 3
The dev server rejects the hostname you open it through
1Check
Next.js blocks cross-origin requests to dev-only assets and endpoints. It allows localhost, its subdomains and the hostname the server started with; every other hostname needs an entry.
grep -n "allowedDevOrigins" next.config.*2Fix
List the hostname only, without scheme or port, and restart next dev.
// next.config.js
module.exports = {
allowedDevOrigins: ['dev.example.com'],
}3Verify
Restart the dev server, reload the page and watch the console for the WebSocket.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Keep one nginx snippet for WebSocket proxying and include it in every site that proxies a dev server.
- Use the map block so one location serves both plain requests and upgrades.
- Write allowedDevOrigins entries without scheme or port; only the hostname is matched.
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
WebSockets behind nginx drop when the connection is idle
transport close
nginx closes a proxied connection when the backend sends no data for 60 seconds, and a quiet WebSocket looks exactly like that.
3 causes, each with a fixServers
A Next.js static export works by clicking links but gives 404 on refresh or deep links
The home page loads, but a direct link to /blog/post-1 returns 404
A static export writes one HTML file per route, such as about.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
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fix