Maaz Zindani

Loading the index…

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

Vite hot reload fails with a WebSocket connection error behind a proxy or HTTPS

ErrorWebSocket connection to 'wss://host:port/' failed

Short answer

Vite's hot module reload talks to the dev server over a WebSocket. Behind a reverse proxy that does not forward WebSocket traffic, or on a page served over HTTPS, the browser cannot open that connection. Make the proxy pass WebSocket, or set the Vite WebSocket client port and protocol to match what the browser reaches.

  • Applies to Vite 7, Vite 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser console on the failing page and note the exact address the client tries. It must be an address the browser can reach, so compare it with how you opened the site.

    # Browser DevTools: Network tab, filter by WS, open the failed request
  2. 2Match what you see, then jump to its fix

    1. 1The page loads through the proxy but the WebSocket request fails or never upgradesThe reverse proxy does not forward WebSocket trafficFix
    2. 2The client tries a port or ws/wss scheme that your proxy does not publishThe client port or protocol differs from what the browser reachesFix
    3. 3The failing address starts with wss:// and the page shows a certificate warningHTTPS dev server with a certificate the browser rejectsFix
    4. 4The dev server runs inside a dev container or behind VS Code port forwarding and connections hangDev container or port forwarding stalls the connectionFix

What does the error look like?

  • WebSocket connection to 'wss://host:port/' failed
  • HMR does not work behind a reverse proxy

Cause 1 of 4

The reverse proxy does not forward WebSocket traffic

1Check

Vite's docs say that with the default configuration, reverse proxies in front of Vite are expected to support proxying WebSocket.

grep -rn -E 'proxy_set_header +(Upgrade|Connection)' /etc/nginx/

2Fix

Configure the proxy to pass WebSocket upgrades to the Vite dev server. nginx treats Upgrade and Connection as hop-by-hop headers, so they must be set explicitly. If you cannot, use the alternatives in the next cause.

# nginx example
location / {
    proxy_pass http://127.0.0.1:5173;
    proxy_http_version 1.1;   # needed before nginx 1.29.7
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

3Verify

Reload the page. The console no longer shows the WebSocket error and edits show up live.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

Cause 2 of 4

The client port or protocol differs from what the browser reaches

1Check

The docs describe server.ws options for protocol, host, port, path and clientPort. They also note that if the HMR client cannot connect through the proxy, it falls back to the HMR server directly.

grep -n -A6 'server' vite.config.ts

2Fix

Either keep strictPort on and make the client port equal to the server port, or give the WebSocket its own port different from the server port.

// vite.config.ts
export default defineConfig({
  server: {
    port: 5173,
    strictPort: true,
    ws: { clientPort: 5173 },
  },
})

3Verify

Restart the dev server and reload the page.

npx vite

Confirmed by vite.dev

Did this fix it?

Cause 3 of 4

HTTPS dev server with a certificate the browser rejects

1Check

When the dev server uses https it needs a valid certificate, and the docs name self-signed certificates as a case that needs the custom WebSocket server setup.

grep -n -B1 -A6 'https' vite.config.ts

2Fix

Use a certificate the browser trusts for the host name you open, or pass your own server to server.ws.server so Vite handles the WebSocket on it.

import fs from 'node:fs'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    },
  },
})

3Verify

Open the https address and check that the console shows no certificate or WebSocket error.

npx vite

Confirmed by vite.dev

Did this fix it?

Cause 4 of 4

Dev container or port forwarding stalls the connection

1Check

Vite's troubleshooting page names dev containers and VS Code port forwarding as a case where connections stall.

grep -n 'host' vite.config.ts

2Fix

Set server.host to 127.0.0.1, as the troubleshooting page advises.

export default defineConfig({
  server: { host: '127.0.0.1' },
})

3Verify

Restart the dev server and reload the page.

npx vite

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Put the WebSocket upgrade headers in the proxy config from the start.
  • Keep the browser address, proxy and Vite port in one short note so the client port can be set correctly.
  • Use the same host name and certificate in the browser and the dev server.

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.

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Web apps

A POST to a Google Apps Script web app returns 405 or a CORS error

Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Apps Script web apps run doPost for POST and doGet for GET, and the Apps Script guides describe no other entry points.

3 causes, each with a fix

Next step

Want this handled for good?

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