Fixing VS Code File Watcher Exhaustion ("ENOSPC: System limit for number of file watchers reached") on Large Projects

The Problem

On Linux (including WSL2), opening a large project in VS Code sometimes fails silently on parts of its tooling: file changes stop being picked up (a file saved outside the editor doesn't trigger a rebuild, git status doesn't refresh, search results go stale), or the editor's Output panel shows an explicit error: Error: ENOSPC: System limit for number of file watchers reached. Restarting VS Code "fixes" it temporarily, which is a strong hint the real cause is a system-wide resource limit, not a bug in the editor itself.

Why It Happens

Linux caps how many files the kernel will watch for changes

VS Code (and many of its extensions — ESLint, Prettier, git integrations, build tool watchers) each register file-system watchers using Linux's inotify subsystem to know when to re-run. Every default Linux distribution ships with a fairly low system-wide inotify watch limit (often 8192), which large projects with many files — especially inside node_modules — blow past quickly.

node_modules and build output are watched by default

Unless explicitly excluded, VS Code's own files.watcherExclude setting doesn't cover every directory a large project might have — generated build folders, multiple node_modules trees in a monorepo, or a .next/dist/coverage directory can each add thousands of watched files that add nothing to the developer experience.

WSL2 has its own separate limit from Windows

On WSL2, the Linux inotify limit applies inside the WSL filesystem even though VS Code's UI is running on Windows — a common point of confusion, since raising a Windows-side setting does nothing for this specific error.

The Fix

1. Raise the system inotify watch limit (persistently)

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

This is the direct fix for the error message itself. 524288 is comfortably high for even large monorepos; on WSL2, run this inside the WSL shell, not PowerShell, since it's the Linux-side limit that applies.

2. Exclude directories VS Code never needs to watch

// .vscode/settings.json
{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/.git/objects/**": true,
    "**/coverage/**": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true
  }
}

Raising the system limit fixes the crash; excluding these directories fixes the underlying waste — thousands of watches on files that never need to trigger anything in the editor.

3. Check what's actually consuming watches before assuming it's your own project

cat /proc/sys/fs/inotify/max_user_watches
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l

On a shared dev machine or a heavily multi-tasked WSL2 setup, another running process (a file sync tool, another editor, a dev server with its own watcher) can be the one actually exhausting the limit, not VS Code.

Why This Works

The system limit controls how many files the kernel is willing to watch at once across every process, not per-application — raising it gives genuine headroom for large projects. Excluding node_modules and build output stops VS Code and its extensions from spending that budget on directories where a change notification was never going to be useful anyway, which keeps the fix effective even as the project grows further.

Conclusion

An ENOSPC file watcher error, or file changes silently not being picked up, is a Linux kernel resource limit being exhausted by the sheer number of files a large project (and its node_modules) contains — not a VS Code bug. Raise fs.inotify.max_user_watches persistently, exclude directories that never need watching, and the editor's file-driven features stay reliable no matter how large the project gets.