System limit for number of file watchers reached (ENOSPC)
Your Linux user has run out of inotify watches, not disk space. How to see and raise the limit, persist it, find what holds watches, and make agents watch less.
Your user account has used up its inotify watches: the kernel’s allowance of files and folders that programs may watch for changes. The disk is not full, whatever ENOSPC says. Every agent, editor, language server and dev server running as that user draws on the same allowance. See the limit with cat /proc/sys/fs/inotify/max_user_watches, raise it with sudo sysctl fs.inotify.max_user_watches=524288, keep it across reboots with a file in /etc/sysctl.d, then restart the program that failed. “Too many open files” on a watch usually means the other limit, max_user_instances. Changing either needs root.
What the message means
The Node-based tools word it like this:
Error: ENOSPC: System limit for number of file watchers reached, watch '/home/user/.claude'CopiedOpenCode reports the same failure in words that read like a full disk:
Error: ENOSPC: no space left on device, watch '/home/user/.config/opencode'CopiedBoth come from the kernel call that adds a watch, and its manual page defines ENOSPC there as “The user limit on the total number of inotify watches was reached or the kernel failed to allocate a needed resource.” The word watch and a path after the error tell it apart from a real full disk; if df -h shows free space, this is the case.
The similar form is EMFILE: too many open files, watch …. Creating a watcher can fail with EMFILE for two reasons, which the manual lists as “The user limit on the total number of inotify instances has been reached” and “The per-process limit on the number of open file descriptors has been reached.” With watchers, the first is the usual one.
The three limits
See all three at once:
sysctl fs.inotifyCopiedmax_user_watches: how many files and folders one user may watch in total. Watching a folder does not cover the folders inside it, so a tool watching a whole project needs a watch for every folder in the tree, and a repository with a largenode_modulesspends thousands on that alone.max_user_instances: how many watchers one user may open; each program usually opens one or a few. The kernel default is 128.max_queued_events: how many change events may wait to be read. Past it, events are dropped and the program is told the queue overflowed. It does not produce the errors above.
The first two are counted per real user ID, not per program. Three agents, an editor’s remote server and a dev server all running as one user share one allowance, and an agent that started fine can fail the moment another program takes the last watches.
The default watch limit depends on the machine. The kernel sets it at boot to allow “up to 1% of addressable memory” for watches, kept between 8,192 and 1,048,576, so a small server gets a small number. Each watch costs kernel memory: the kernel allocates a record for it and keeps the watched file’s inode in memory, and budgets each watch at that record plus the size of two inodes. The limit is a ceiling; memory is spent on the watches programs actually create.
Raise the limits
For the running system, until the next reboot:
sudo sysctl -w fs.inotify.max_user_watches=524288
sudo sysctl -w fs.inotify.max_user_instances=512CopiedTo keep them, put them in a file under /etc/sysctl.d/, which systemd reads at boot, and load it now:
printf 'fs.inotify.max_user_watches = 524288\nfs.inotify.max_user_instances = 512\n' | sudo tee /etc/sysctl.d/60-inotify.conf
sudo sysctl --systemCopiedThese are the values users give each other on the agents’ trackers, and a starting point rather than a rule: 1,048,576 is the highest the kernel picks for itself on a large machine. Without root you cannot change either limit; on a shared machine, ask whoever administers it.
Then restart what failed. Claude Code and OpenCode have both been reported to stop at startup when a watch fails, so the session that showed the error does not recover on its own.
Find what holds the watches
Each inotify watcher a process has open is listed in /proc/<pid>/fdinfo, with one line beginning with inotify per watched file or folder. Counting those lines per process gives the biggest holders:
sudo sh -c 'for p in /proc/[0-9]*; do n=$(cat $p/fdinfo/* 2>/dev/null | grep -c "^inotify"); [ "$n" -gt 0 ] && echo "$n $(cat $p/comm) ${p#/proc/}"; done | sort -rn | head'CopiedEach line is the count, the program’s name and its process id. Without sudo you see only your own processes, which is enough when the agents run as you. If one process holds hundreds of thousands, raising the limit will only move the wall; that program is watching too much.
Make the tools watch less
OpenCode has a documented setting, watcher.ignore, for files and folders that “should not trigger filesystem updates”. Add your build output and anything else large:
{
"watcher": {
"ignore": ["dist/**", "coverage/**"]
}
}CopiedClaude Code documents no setting to turn its watching off. The reports on its tracker show it watching its own settings and the ~/.claude folder, which costs few watches, so when it fails it is likely the last program to ask rather than the one spending them; the list above shows which is.
Codex: an open report has the Codex extension for VS Code climbing to around a million watches in a large workspace. One user there found that raising the limit from 524,288 to 2,097,152 “did not reliably restore the panel”. The count comes from the editor’s extension, not the codex command in a terminal.
The dev server an agent starts. Vite’s watcher skips .git/, node_modules/ and its build output by default, and its server.watch option takes more exclusions; other dev servers have their own setting for the same thing.
Since the limits are per user, agents running under separate Linux accounts each get their own allowance instead of sharing one. What else several agents on one machine compete for is measured in how many coding agents fit on one server.
When raising the watches does not help
If the error is EMFILE, or the agent hangs at a blank screen instead of failing, check max_user_instances. OpenCode 2.3.0 has been reported to hang silently at startup when no watcher can be opened, and a change to skip the watch instead was still open on November 19, 2026. Its maintainer’s first question on the ENOSPC crash was the right one for any agent: “Are you working in a really big repository?” A tree with millions of files wants a higher limit and an ignore list; a count that keeps climbing in one process while nothing on disk changes is a leak, which only a restart, and a report on that tool’s tracker, will clear.