Vite hot reload fails with a WebSocket connection error behind a proxy or HTTPS
WebSocket connection to 'wss://host:port/' failedShort 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.
Fix it fast
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 request2Match what you see, then jump to its fix
- 1
The page loads through the proxy but the WebSocket request fails or never upgradesThe reverse proxy does not forward WebSocket trafficFix - 2
The 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
The failing address starts with wss:// and the page shows a certificate warningHTTPS dev server with a certificate the browser rejectsFix - 4
The dev server runs inside a dev container or behind VS Code port forwarding and connections hangDev container or port forwarding stalls the connectionFix
- 1
What does the error look like?
WebSocket connection to 'wss://host:port/' failedHMR 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 nginxConfirmed by nginx.org
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.ts2Fix
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 viteConfirmed by vite.dev
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.ts2Fix
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 viteConfirmed by vite.dev
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.ts2Fix
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 viteConfirmed by vite.dev
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 fixWeb apps
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 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
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Apollo Client is blocked by CORS when the GraphQL server runs on AWS Lambda
No 'Access-Control-Allow-Origin' header is present on the requested resource.
Apollo Server does not set CORS for you when it runs behind a framework or integration, and on Lambda that layer is API Gateway.
5 causes, each with a fixWeb 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