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

ReactINTERMEDIATEMEDIUMUpdated Dec 11, 2025· 318 views

This error occurs when Vite cannot establish a WebSocket connection for Hot Module Replacement, preventing live updates during development. It typically happens with proxy servers, Docker environments, or incorrect network configurations.

Quick fix

Fixes Vite HMR connection failed, make sure your config is correct

// 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
    }
  }
})
  1. Verify the WebSocket connection in browser DevTools
  2. Configure HMR settings in vite.config.js for custom setups
  3. Enable file system polling for Docker and WSL2
  4. Fix HTTPS and SSL WebSocket protocol mismatch
react — error
// 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
    }
  }
})
Vite HMR connection failed, make sure your config is correct

What this error means

This error indicates that Vite's development server cannot establish or maintain a WebSocket connection required for Hot Module Replacement (HMR). HMR allows Vite to push code changes to your browser without a full page reload, providing instant feedback during development. The WebSocket connection is essential for Vite's fast development experience. When this connection fails, you'll lose live updates and may need to manually refresh your browser to see changes. The error message "make sure your config is correct" points to potential misconfiguration in your vite.config.js file, particularly in the server.hmr settings. Common scenarios include running Vite behind reverse proxies (nginx, Apache), inside Docker containers, on WSL2, over HTTPS with SSL certificates, or when using custom ports that don't match the actual dev server port.

Typical symptoms

  • Changes to code don't reflect in the browser without manual refresh
  • Console shows "[vite] failed to connect to websocket" error
  • Browser DevTools Network tab shows failed WebSocket connection (ws:// or wss://)
  • Error message "WebSocket connection to 'ws://localhost:5173/' failed"
  • HMR overlay displays connection error in development
  • Vite dev server runs but hot reload stops working

Common causes

  1. Incorrect HMR port configuration in vite.config.js when using custom ports
  2. Running Vite inside Docker container without proper host and port mapping
  3. Using WSL2 on Windows with file watching disabled or polling not enabled
  4. HTTPS/SSL setup with mismatched WebSocket protocol (ws:// vs wss://)
  5. Reverse proxy (nginx, Apache) without WebSocket support configured
  6. Firewall or ad blocker blocking WebSocket connections on development ports
  7. Browser accessing dev server via different hostname than configured (localhost vs 127.0.0.1 vs [::1])
  8. Port conflicts where Vite falls back to different port but WebSocket uses original

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

1Verify the WebSocket connection in browser DevTools

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.

2Configure HMR settings in vite.config.js for custom setups

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

javascript
// 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:

bash
docker run -p 5173:5173 your-image
3Enable file system polling for Docker and WSL2

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

javascript
// 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:

bash
CHOKIDAR_USEPOLLING=true CHOKIDAR_INTERVAL=100 npm run dev
4Fix HTTPS and SSL WebSocket protocol mismatch

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

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

For custom SSL certificates:

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

5Configure reverse proxy for WebSocket support

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

Nginx configuration:

nginx
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:

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

6Check for firewall and network blocking

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:

bash
vite --host 127.0.0.1

Advanced notes

WSL2-specific considerations: When running VS Code from Windows with files in the WSL2 filesystem, file watching may not work reliably because Windows processes can't detect changes made to files in the WSL2 filesystem. Launch VS Code from within WSL2 using code . from the WSL terminal to ensure all file operations happen natively in WSL.

Debug mode: Run Vite with debug flags to see detailed HMR information:

bash
vite --debug hmr

This will log circular dependency paths and other HMR-related information that may help diagnose connection issues.

Port conflicts: If Vite automatically switches to a different port (e.g., 5174) because 5173 is occupied, the WebSocket client may still try to connect to the original port. Always check which port Vite actually started on in the console output and ensure your HMR configuration matches.

Shopify embedded apps: When using --use-localhost flag with Shopify CLI, you may need to configure hmr.clientPort to match the tunnel port rather than the local dev server port.

Multiple Vite servers: If running multiple Vite projects simultaneously, ensure each uses a unique port to avoid WebSocket connection conflicts.

Frequently asked questions

What does "Vite HMR connection failed, make sure your config is correct" mean?
This error indicates that Vite's development server cannot establish or maintain a WebSocket connection required for Hot Module Replacement (HMR). HMR allows Vite to push code changes to your browser without a full page reload, providing instant feedback during development. The WebSocket connection is essential for Vite's fast development experience.
How do I fix "Vite HMR connection failed, make sure your config is correct"?
This error occurs when Vite cannot establish a WebSocket connection for Hot Module Replacement, preventing live updates during development. It typically happens with proxy servers, Docker environments, or incorrect network configurations.
What causes "Vite HMR connection failed, make sure your config is correct"?
Incorrect HMR port configuration in vite.config.js when using custom ports Running Vite inside Docker container without proper host and port mapping Using WSL2 on Windows with file watching disabled or polling not enabled
Is the "Vite HMR connection failed, make sure your config is correct" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading