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

Matthew C.

—September 15, 2024

The ProblemThe Problem

After upgrading to Next.js version 12+, you may get the following error in your browser dev tools console when running your development server:

WebSocket connection to 'wss://app_url/_next/webpack-hmr' failed: Websocket is closed before connection is established

The SolutionThe Solution

From version 12 onward, Next.js uses a WebSockets connection for Hot Module Replacement (HMR) instead of a server-sent events connection. The above error occurs when an incorrectly configured proxy server disrupts this WebSockets connection.

If you are using a proxy or a custom server to serve a Next.js app over HTTPS during development (for example, so that you can use an API that requires HTTPS), you need to configure your server to handle WebSockets traffic without connection disruptions.

This solution demonstrates the correct configuration for three common proxy servers: NGINX, Apache, and custom servers.

NGINX Proxy Server ConfigurationNGINX Proxy Server Configuration

If you’re using NGINX, add the following configuration:

location /_next/webpack-hmr {
    proxy_pass http://localhost:3000/_next/webpack-hmr;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

This informs the NGINX proxy server that the client’s HTTP protocol will be upgraded to a WebSockets connection. The headers have to be passed explicitly.

Consult the NGINX docs to learn more about WebSocket proxying.

Apache Proxy Server ConfigurationApache Proxy Server Configuration

If you’re using Apache (2.x), you can add the following configuration to enable WebSockets to the server:

<VirtualHost *:443>
 # ServerName yourwebsite.local
 ServerName "${WEBSITE_SERVER_NAME}"
 ProxyPass / http://localhost:3000/
 ProxyPassReverse / http://localhost:3000/
 # Next.js 12 uses websocket
 <Location /_next/webpack-hmr>
    RewriteEngine On
    RewriteCond %{QUERY_STRING} transport=websocket [NC]
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule /(.*) ws://localhost:3000/_next/webpack-hmr/$1 [P,L]
    ProxyPass ws://localhost:3000/_next/webpack-hmr retry=0 timeout=30
    ProxyPassReverse ws://localhost:3000/_next/webpack-hmr
 </Location>
</VirtualHost>

Consult the Apache docs to learn more about upgrading an HTTP connection to a WebSockets connection.

Custom Server ConfigurationCustom Server Configuration

If you’re using a custom server, you may need to ensure that the request is passed correctly. In an Express app, you can pass the request to a Next.js request handler:

app.all('/_next/webpack-hmr', (req, res) => {
  nextjsRequestHandler(req, res)
})

NoteNote

Next.js version 12+ uses the WebSockets connection for HMR because it speeds up the development process by updating an app in the development server whenever its source code is changed.

For example, when you edit your app source code while the development server is running, HMR updates the app in the development server, by replacing, adding, or removing modules without needing a full reload.