Node.js "ENOSPC: System limit for file watchers reached" in CI

A file watcher tried to register more inotify watches than the kernel allows. Tools like nodemon or a dev server watching a large tree exhaust fs.inotify.max_user_watches and fail with ENOSPC.

What this error means

Starting a watcher (nodemon, a dev server) in CI fails with ENOSPC: System limit for number of file watchers reached. The disk is not full; the inotify watch limit is.

node

Error: ENOSPC: System limit for number of file watchers reached,
watch '/work/repo/node_modules'
  errno: -28,
  code: 'ENOSPC',
  syscall: 'watch'

Common causes

The inotify watch limit is too low

The default max_user_watches is small relative to a large project tree, so the watcher runs out of watches.

Watching node_modules or build output

A watcher that recurses into node_modules or generated folders registers far more watches than necessary.

How to fix it

Raise the inotify watch limit

Increase fs.inotify.max_user_watches before starting the watcher.

workflow

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

Avoid watching in CI, or narrow the watch

Most CI jobs do not need a watcher at all. If one is required, exclude node_modules and build output.

Use the non-watch build/test command in CI (drop nodemon).
If watching is required, ignore node_modules and dist.
Limit the watch to source directories only.

How to prevent it

Use non-watching commands in CI wherever possible.
Exclude node_modules and generated output from watchers.
Raise max_user_watches when a watcher is genuinely needed.