CI "inotify watch limit reached" (ENOSPC) - Raise max_user_watches
A confusing ENOSPC that has nothing to do with disk space: a watcher hit the inotify watch limit. The kernel reuses the ENOSPC errno when fs.inotify.max_user_watches is exhausted, so the message says "no space" but means "no more watches".
What this error means
A dev server, bundler, or test watcher fails with ENOSPC: System limit for number of file watchers reached or inotify watch limit reached, even though df -h shows free disk. It happens when watching a large tree (e.g. node_modules).
Error: ENOSPC: System limit for number of file watchers reached,
watch '/app/node_modules/.../src'Common causes
Too many files watched at once
File watchers register one inotify watch per directory/file. Watching a huge tree (node_modules, a monorepo) can exceed fs.inotify.max_user_watches, which the kernel reports as ENOSPC.
A low default watch limit
Some images set a small max_user_watches (e.g. 8192). File-heavy projects blow past it the moment a watcher starts.
How to fix it
Raise the inotify watch limit
Increase the kernel limit for the job; this is the standard fix.
sysctl fs.inotify.max_user_watches # current limit
sudo sysctl -w fs.inotify.max_user_watches=524288Watch fewer files (or do not watch at all)
- Exclude large directories (
node_modules, build output) from the watcher. - In CI, run tools in non-watch/CI mode (
--watch=false,CI=true) since watching is rarely needed in a one-shot job. - Use polling only as a last resort - it is slower but avoids inotify entirely.
How to prevent it
- Set a generous
fs.inotify.max_user_watcheson runners that build file-heavy projects. - Disable file watching in CI runs that do not need it.
- Exclude dependency and build directories from watchers.
Frequently asked questions
Why does it say ENOSPC / "no space" when the disk is not full?
max_user_watches, not disk space - df -h will show free bytes.