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.
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.
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-imageDocker 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 devIf 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.1WSL2-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:
vite --debug hmrThis 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.
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency
Cannot use private fields in class components without TS support
Cannot use private fields in class components without TS support
Cannot destructure property 'xxx' of 'undefined'
Cannot destructure property of undefined when accessing props
useNavigate() may be used only in the context of a <Router> component.
useNavigate() may be used only in the context of a Router component
Cannot find module or its corresponding type declarations
How to fix "Cannot find module or type declarations" in Vite