ViteHMRError Fix2026 Updated

Vite HMR Not Working— Hot Module Replacement Fixed [2026]

Also covers: file watcher limits · WSL2 polling · React Fast Refresh · HMR host config · full page reload causes

January 20266 min readVite 5/6 · React · TypeScript

⚡ Symptoms

Error
[vite] page reloaded          ← full reload instead of HMR update
[vite] server connection lost ← WebSocket dropped
# OR: edits don't update browser at all
# OR: component state resets on every save (Fast Refresh not working)

✅ Fastest diagnostics

Check these in order
1. Browser console: look for '[vite] connected.' on load
2. Linux/WSL2: check file watcher limit → sudo sysctl fs.inotify.max_user_watches
3. WSL2 editing Windows files → enable usePolling in vite.config.ts
4. React: confirm @vitejs/plugin-react is in vite.config.ts plugins

Why Vite HMR Stops Working

Vite HMR relies on two things: the OS file watcher detecting file changes, and a WebSocket connection from the browser to the dev server. If either breaks, HMR fails. On Linux and WSL2, the inotify watcher limit is often hit in large projects. In Docker and WSL2 with Windows files, polling is required instead.

1

Increase OS File Watcher Limit (Linux/WSL2)

ENOSPC: System limit for number of file watchers reached
2 min
Error
Error: ENOSPC: System limit for number of file watchers reached
Increase inotify limit — Linux and WSL2
# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Temporary fix (resets on reboot)
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl -p

# Permanent fix — add to /etc/sysctl.conf
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# For WSL2 — add to /etc/sysctl.d/99-vite.conf
sudo sh -c 'echo "fs.inotify.max_user_watches=524288" > /etc/sysctl.d/99-vite.conf'
2

Enable Polling for WSL2 and Network Drives

WSL2 editing Windows files — inotify doesn't receive events
2 min
vite.config.ts — enable polling
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"

export default defineConfig({
  plugins: [react()],
  server: {
    watch: {
      // ✅ Use polling when inotify doesn't work (WSL2, Docker, NFS, network drives)
      usePolling: true,
      interval: 100,       // poll every 100ms — lower = faster but more CPU
    },
  },
})

// Only enable polling when needed — it uses more CPU than inotify.
// Set via env variable to avoid committing it for teammates on macOS/Windows:
export default defineConfig({
  server: {
    watch: {
      usePolling: process.env.VITE_USE_POLLING === "true",
    },
  },
})
// Then in .env.local (gitignored): VITE_USE_POLLING=true
3

Fix React Fast Refresh Not Working

State resets on every save — Fast Refresh not activating
3 min

React Fast Refresh only activates when a file exports only React components. Mixing component and non-component exports in the same file disables Fast Refresh for that file.

Fast Refresh rules — what breaks it
// vite.config.ts — ensure @vitejs/plugin-react is present
import react from "@vitejs/plugin-react"
export default defineConfig({ plugins: [react()] })

// ❌ Mixing component + non-component export — disables Fast Refresh
// components/Button.tsx:
export const BUTTON_SIZES = ["sm", "md", "lg"] as const   // ← constant — breaks Fast Refresh
export function Button({ size }) { return <button /> }

// ✅ Move constants to a separate file
// constants/button.ts:
export const BUTTON_SIZES = ["sm", "md", "lg"] as const

// components/Button.tsx — only exports the component:
export function Button({ size }) { return <button /> }

// ❌ Anonymous default export — Fast Refresh can't track it
export default () => <div>Hello</div>

// ✅ Named function component as default export
export default function HomePage() { return <div>Hello</div> }

The Vite console logs a warning when Fast Refresh is disabled for a file: '(!) Could not Fast Refresh Button.tsx. Export of non-component detected.' Move non-component exports to separate files to re-enable Fast Refresh.

4

Configure HMR Host and Port Explicitly

HMR disconnects when accessed via proxy, tunnel, or custom host
2 min
vite.config.ts — explicit HMR settings
export default defineConfig({
  server: {
    host: "0.0.0.0",    // bind to all interfaces (needed for Docker/remote access)
    port: 5173,

    hmr: {
      // Explicitly set HMR WebSocket host and port
      // Needed when Vite is behind a reverse proxy or accessed via tunnel
      host: "localhost",
      port: 5173,
      protocol: "ws",    // or "wss" for HTTPS

      // For ngrok or remote tunnels:
      // host: "your-tunnel-id.ngrok.io",
      // protocol: "wss",
      // clientPort: 443,
    },
  },
})

// For Docker — override via environment:
// VITE_ALLOW_EXTERNAL_ORIGIN=true or configure allowedHosts:
export default defineConfig({
  server: {
    allowedHosts: ["myapp.local", ".ngrok.io"],
  },
})
5

Identify Modules That Cause Full-Page Reloads

Specific file edits always trigger full reload — find the boundary
3 min

Vite logs the reason for a full page reload in the browser console and terminal. Use this to identify which modules have no HMR boundary.

Reading Vite HMR logs
// Browser console — Vite HMR messages:
// [vite] connected.                                ← WebSocket connected
// [vite] hot updated: /src/components/Button.tsx  ← successful HMR
// [vite] page reloaded                            ← full reload (no HMR boundary)

// Terminal — Vite dev server logs:
// hmr update /src/components/Button.tsx
// hmr invalidate /src/main.tsx  The update boundary is out of date.

// Common causes of full page reload:
// 1. File exports non-React values alongside components
// 2. Module is in the HMR boundary root (e.g. main.tsx imports everything)
// 3. Circular imports break the HMR graph
// 4. CSS-in-JS or runtime style injection without HMR support

// Fix — add explicit HMR accept at the module level if needed:
// (advanced — usually not required)
if (import.meta.hot) {
  import.meta.hot.accept()   // this module handles its own HMR updates
}

Prevention

Frequently Asked Questions

Why does Vite do a full page reload instead of HMR?+
A full page reload happens when Vite cannot isolate the change to a hot-updatable module. This occurs when: a module has no HMR boundary (like a file that exports constants used everywhere), the React Fast Refresh plugin is missing, or the changed module is in the module graph root. Check the Vite console — it logs 'page reloaded' with a reason.
Why does Vite HMR not work in WSL2?+
WSL2 runs Linux inside a virtual machine, and the Windows filesystem is mounted via a network share (9P protocol). The Linux inotify file watcher doesn't receive events for files on the Windows drive. Fix this by enabling polling in vite.config.ts: server: { watch: { usePolling: true } }.
What is React Fast Refresh and how does it differ from HMR?+
React Fast Refresh is a React-specific HMR implementation that preserves component state during updates. Standard HMR replaces the module but resets state. Fast Refresh is provided by @vitejs/plugin-react and requires components to follow specific rules: only export React components from the file, don't export non-component values alongside components.
How do I check if Vite HMR is connected?+
Open the browser console — Vite logs '[vite] connected.' on startup. If you see '[vite] server connection lost' or no Vite logs at all, HMR is disconnected. Also check the Network tab for a WebSocket connection to your Vite dev server — HMR uses WebSocket for communication.
Can I disable HMR in Vite?+
Yes — set server: { hmr: false } in vite.config.ts. This is useful for debugging full-page reload behaviour. You can also set hmr: { overlay: false } to keep HMR enabled but disable the error overlay.
Why does editing a CSS file cause a full page reload in Vite?+
Vite normally handles CSS changes with HMR without a page reload. If CSS changes cause full reloads, the CSS file is likely imported in a module that has no HMR boundary. Try importing global CSS in main.tsx and component-level CSS as CSS Modules. Also check for PostCSS config errors that may break the CSS transform pipeline.

Need Expert Help?

We Build React Apps with Vite

Softplix engineers configure Vite for fast HMR, optimised builds, and production-ready React apps. Let us help.

Talk to an Engineer