How to fix Vite HMR connection failed, make sure your config is correct in React

Open your browser's DevTools (F12), go to the Network tab, and filter by "WS" (WebSocket).

Look for a connection attempt to ws://localhost:5173/ or similar. Check the status:
- If it shows "101 Switching Protocols", the connection succeeded
- If it shows "Failed" or "Pending", there's a connection issue

Also check the Console tab for specific error messages like "[vite] failed to connect to websocket" which may include details about the attempted URL.

If you're using Docker, proxies, or custom ports, explicitly configure the HMR connection:

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0', // Required for Docker
    port: 5173,
    hmr: {
      clientPort: 5173, // Port browser should connect to
      // For custom domains or proxies:
      // host: 'yourdomain.com',
      // protocol: 'wss', // Use 'wss' for HTTPS
    }
  }
})

For Docker specifically, ensure your port mappings match:

docker run -p 5173:5173 your-image

Docker and WSL2 environments often have issues with file system watching. Enable polling to fix this:

// vite.config.js
export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      usePolling: true,
      interval: 100 // Optional: adjust polling frequency in ms
    }
  }
})

Note: Polling is more CPU-intensive than native file watching, but it's necessary when file change events don't propagate correctly.

Alternatively, you can set environment variables:

CHOKIDAR_USEPOLLING=true CHOKIDAR_INTERVAL=100 npm run dev

If you're serving your app over HTTPS, the WebSocket must also use secure protocol (wss://):

// vite.config.js
export default defineConfig({
  server: {
    https: true, // Enable HTTPS
    hmr: {
      protocol: 'wss', // Use secure WebSocket
      host: 'localhost'
    }
  }
})

For custom SSL certificates:

import fs from 'fs'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./cert/key.pem'),
      cert: fs.readFileSync('./cert/cert.pem')
    },
    hmr: {
      protocol: 'wss'
    }
  }
})

Browsers block insecure WebSocket (ws://) connections from HTTPS pages for security reasons.

If using nginx or another reverse proxy, ensure WebSocket connections are properly forwarded:

Nginx configuration:

location / {
    proxy_pass http://localhost:5173;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Then update vite.config.js:

export default defineConfig({
  server: {
    hmr: {
      host: 'yourdomain.com',
      protocol: 'wss', // If using HTTPS
      port: 443 // Match your proxy port
    }
  }
})

The Upgrade and Connection headers are essential for WebSocket handshake.

Verify nothing is blocking WebSocket connections:

1. Disable browser extensions temporarily: Some ad blockers or security extensions block WebSocket connections
2. Check firewall rules: Ensure port 5173 (or your custom port) is allowed for incoming connections
3. Test with 127.0.0.1 instead of localhost: Some systems have IPv6 issues where localhost resolves to [::1] but the server only binds to IPv4

Try accessing your app using different addresses:
- http://127.0.0.1:5173
- http://localhost:5173
- http://0.0.0.0:5173 (if running in Docker)

You can also force Vite to use IPv4:

vite --host 127.0.0.1