Diagnosing Vite.js Hot Module Replacement Failures: Symptoms, Checks, and Fixes

Recognizable condition

You start the Vite dev server, edit a source file, and the browser either does not update, reloads the whole page, or shows a WebSocket error. This indicates that Hot Module Replacement (HMR) is not working as expected.

Useful takeaway

By following a short symptom‑cause table, performing ordered checks, and applying the fix that matches the finding, you can restore HMR without guessing.

Cause / diagnostic table

Symptom	Likely cause
Edits to JS/TS files do not appear; no reload	File watcher ignores the edited directory (e.g., matches node_modules, .git) or lacks OS permission for chokidar.
Saving a file triggers a full page reload	Missing or misconfigured plugin for the file type (e.g., .vue without @vitejs/plugin-vue) or plugin order overrides HMR hooks.
HMR works for some files but not others, or works intermittently	Plugin version mismatch or plugin order causing HMR hooks to be overridden.
Console shows "[vite] HMR connection lost" or WebSocket errors	Proxy, VPN, or corporate firewall blocks the WebSocket to /@vite/client.
Editing CSS/SCSS/Less results in full reload instead of style injection	Missing preprocessor plugin (e.g., sass, less) or missing PostCSS config.

Ordered checks

1. Verify the dev server is running

   Run npm run dev (or vite) in the project root. Ensure you have read/write permission on the project directory.

2. Check the console for HMR logs

   Open Chrome DevTools → Console. After saving a file, look for a line like [vite] HMR updated ./src/main.js. Absence of this line indicates the server did not detect the change.

3. Inspect the WebSocket connection

   In DevTools → Network, filter for WS. Confirm a connection to http://localhost:5173/@vite/client (or your Vite port) with status 101 and that it stays open while you edit.

4. Review vite.config.js

   Look for missing plugins, incorrect server.watch ignores, or plugin order that could override HMR. Example of a problematic config:

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   
   export default defineConfig({
     plugins: [vue()],
     server: {
       watch: {
         // Accidentally ignoring the src folder
         ignored: ['!**/src/**']
       }
     }
   })

   The ignored pattern above would prevent Vite from watching any file under src.

5. Confirm required preprocessor plugins

   If you edit .scss files, ensure sass (or dart-sass) is installed and listed in devDependencies. Vite will automatically use it, but if missing, it falls back to treating the file as a static asset, causing a full reload.

6. Test network intermediaries

   Temporarily disable any proxy, VPN, or corporate firewall and repeat the edit. If HMR works, the intermediary was blocking the WebSocket.

Fixes tied to findings

• File watcher not tracking
  • Remove or correct any server.watch.ignored patterns that match your source files.
  • Ensure the user running vite has read permission on the project directory (no need for elevated privileges).
• Missing/misconfigured plugin
  • Install the official plugin for your framework: npm i -D @vitejs/plugin-vue for Vue, npm i -D @vitejs/plugin-react for React, etc.
  • Add the plugin to the plugins array in vite.config.js.
  • Check plugin order: plugins that alter the module graph (e.g., vite-plugin-svgr) should be placed before framework plugins if they need to run first.
• Plugin version mismatch
  • Run npm list @vitejs/plugin-vue (or the relevant plugin) to see installed versions.
  • Upgrade to the latest compatible version: npm update @vitejs/plugin-vue.
  • Consult the plugin’s changelog for breaking changes that affect HMR.
• WebSocket blocked
  • Configure your proxy to allow traffic to http://localhost:[port]/@vite/client.
  • If using a corporate VPN, ask network staff to whitelist the Vite dev server port or split‑tunnel the traffic.
  • As a quick test, run the dev server on a different port (vite --port 3000) and see if the issue persists.
• Missing preprocessor
  • Install the required preprocessor: npm i -D sass for SCSS, npm i -D less for Less, npm i -D stylus for Stylus.
  • Ensure you have a valid postcss.config.js if you rely on PostCSS plugins (e.g., autoprefixer).

Escalation criteria

If after applying the relevant fix the HMR still does not work:

1. Create a minimal reproducible example (clone the repo, remove unrelated dependencies, keep only vite, the framework plugin, and a single src/main.js that imports a component).
2. Run vite --debug to get verbose logs; look for lines containing watch, hmr, or WebSocket.
3. Share the logs and the minimal vite.config.js in the Vite GitHub Discussions or Stack Overflow with the tag vitejs and hmr.

Escalate only after you have verified that the dev server starts without errors, the file watcher is active (you see [vite] dev server running at: in the terminal), and the WebSocket connection is established but no HMR updates are logged.