Maaz Zindani

Loading the index…

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

WebSocket to /_next/webpack-hmr fails when the Next.js dev server is behind nginx

ErrorWebSocket connection to 'ws://localhost/_next/webpack-hmr' failed: WebSocket is closed before the connection is established

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

  • Applies to Next.js 15, Next.js 16, nginx 1.26, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The handshake does not return 101 Switching Protocolsnginx does not pass the Upgrade and Connection headersFix
    2. 2Headers are set as above, but the handshake still does not return 101nginx older than 1.29.7 proxies with HTTP/1.0Fix
    3. 3You 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

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 nginx

Confirmed by nginx.org

Did this fix it?

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 -v

2Fix

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 nginx

Confirmed by nginx.org

Did this fix it?

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 dev

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

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