Node.js ENOSPC: System Limit for Number of File Watchers Reached

Fix the inotify ENOSPC error on Linux when dev servers and editors exhaust file watchers, by raising fs.inotify.max_user_watches.

intermediatedebuggingnodelinuxfilesystem

Symptoms

Error: ENOSPC: System limit for number of file watchers reached
Vite, webpack, or nodemon stops detecting file changes
The error appears when opening a large monorepo

Possible causes

fs.inotify.max_user_watches is set below the number of files being watched
Multiple tools (IDE, dev server, test runner) watch the same tree
node_modules or build output is being watched unnecessarily
A Docker container inherits a low host or per-container limit

Diagnosis steps

Read the current inotify limits

cat /proc/sys/fs/inotify/max_user_watches

Interpretation

Defaults near 8192 are far below what a modern node_modules tree requires.

Count watched instances

cat /proc/sys/fs/inotify/max_user_instances

Interpretation

If many processes watch files, the instance limit can also be exceeded before the watch limit.

Raise the limit and retry

sudo sysctl fs.inotify.max_user_watches=524288

Interpretation

If the error clears immediately, the cause was the configured cap rather than a tool bug.

Root cause

Linux uses inotify to report file changes, and the kernel caps the total watches per user via fs.inotify.max_user_watches. Editors and dev servers each register a watch per file; a large dependency tree can exceed the default cap, after which any additional watch registration fails with ENOSPC.

Fix

Raise fs.inotify.max_user_watches (and max_user_instances) persistently via /etc/sysctl.d, and exclude directories that never need watching such as node_modules, .git, and build output. In containers, set the limit on the host or with a sidecar and use polling as a last resort.

Verify the fix

After raising the limit, restart the dev server and edit a watched file; the change should be detected without ENOSPC and /proc/sys/fs/inotify/max_user_watches should show the new value.

Symptoms

Dev servers and editors report ENOSPC: System limit for number of file watchers reached, then silently stop noticing changes. It appears after opening a large repository or enabling another watcher.

Diagnosis

Check the kernel limits:

cat /proc/sys/fs/inotify/max_user_watches
cat /proc/sys/fs/inotify/max_user_instances

Compare with the size of the watched tree; a node_modules of 200k files dwarfs a default of 8192.

Fix

Raise the limits persistently:

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

Then configure your tool to ignore node_modules, .git, and dist.

Verification

Restart the watcher, touch a tracked file, and confirm the change is detected. Re-read the sysctl value to confirm it persisted.

Why Polling Is the Last Resort

Switching a watcher to polling sidesteps inotify limits but trades them for continuous stat calls that burn CPU on large trees. Prefer raising the kernel limit and pruning the watched set. In containers, remember the namespace has its own accounting: if the host allows 524288 watches, raise the value inside the container definition too, otherwise the low default still applies and the ENOSPC returns under load.