Fix Node.js ENOSPC: System limit for number of file watchers reached

The situation

Running npm start or npm run dev and it dies with:

Error: ENOSPC: System limit for number of file watchers reached, watch '/path/to/project'
    at FSWatcher. (/project/node_modules/chokidar/lib/fsevents-handler.js:180:19)

Linux has a kernel-level cap on how many files and directories it can watch simultaneously via inotify. Between node_modules (which can contain 50,000+ files in a modern project), your source tree, and other processes like VSCode or Dropbox — you've blown past it.

Common triggers: starting a webpack dev server, running nodemon, opening a large monorepo in VSCode, or spinning up multiple dev servers at once.

Debug: confirm it's an inotify limit

Check the current limit and usage:

# Current max watchers
cat /proc/sys/fs/inotify/max_user_watches

# How many instances are allowed
cat /proc/sys/fs/inotify/max_user_instances

# See which processes are consuming watches
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | \
  awk -F/ '{print $3}' | xargs -I{} sh -c 'echo -n "{}: "; cat /proc/{}/cmdline | tr "\0" " "; echo'

A default Linux install sets max_user_watches to just 8192. That's the culprit. A mid-size Next.js or CRA project can chew through 8,000–15,000 watchers on its own — node_modules alone accounts for most of that.

Quick fix (temporary, lost on reboot)

sudo sysctl fs.inotify.max_user_watches=524288

Run your dev server immediately after. If it starts cleanly, the fix works — but it won't survive a reboot. Make it permanent next.

Permanent fix

Write the value to sysctl.conf:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

On Ubuntu 20.04+ and Debian, the cleaner approach is a dedicated config file:

echo 'fs.inotify.max_user_watches=524288' | sudo tee /etc/sysctl.d/99-inotify-watches.conf
sudo sysctl --system

Either works. The 524288 (~512K) value is the community standard — webpack docs, Next.js issues, and years of Stack Overflow answers all converge here. Running a monorepo or multiple projects simultaneously? Double it:

# For monorepos or multiple projects open at once
echo 'fs.inotify.max_user_watches=1048576' | sudo tee /etc/sysctl.d/99-inotify-watches.conf
sudo sysctl --system

Verify the fix

# Confirm the new value is active
cat /proc/sys/fs/inotify/max_user_watches
# Should output: 524288

Restart your dev server. It should come up clean. Running on WSL2? There's one more step.

WSL2 note

WSL2 doesn't apply sysctl.conf changes at boot the same way a native Linux install does. Two options:

Add a startup command to /etc/wsl.conf (recommended):

[boot]
command = sysctl -w fs.inotify.max_user_watches=524288

Or set it in your shell profile as a fallback:

# In your ~/.bashrc or ~/.zshrc
if [ -f /proc/sys/fs/inotify/max_user_watches ]; then
  sudo sysctl -w fs.inotify.max_user_watches=524288 > /dev/null 2>&1
fi

The wsl.conf approach is cleaner — use that one.

Bonus: reduce watcher usage instead of raising the limit

No root access? On a shared server or container with restricted privileges, trim what gets watched instead:

• Add node_modules to .watchmanconfig ignore list if using Watchman
• In webpack, set watchOptions.ignored: /node_modules/
• In Vite, configure server.watch.ignored
• In VSCode, add node_modules and build folders to files.watcherExclude in settings

// vite.config.ts
export default defineConfig({
  server: {
    watch: {
      ignored: ['**/node_modules/**', '**/dist/**']
    }
  }
})

// webpack.config.js
module.exports = {
  watchOptions: {
    ignored: /node_modules/,
  }
}

Lessons learned

• The default 8192 limit predates npm — raise it on every Linux dev machine at setup time, before you ever hit this error
• Large projects compound fast: editor + dev server + test watcher can each consume thousands of watches simultaneously
• VSCode alone eats thousands of watchers on a big repo — check files.watcherExclude in your settings if you keep hitting this
• Docker containers inherit the host's inotify limit — fix it on the host, not inside the container
• Each watcher costs roughly 1KB of kernel memory; bumping to 524288 uses ~512MB at absolute maximum, and in practice far less