The Situation

You open VS Code on a Linux machine — a Node.js monorepo, a React app drowning in node_modules, or just a large workspace — and you see this:

Error: ENOSPC: System limit for number of file watchers reached, watch '/home/user/project/src'

VS Code stops tracking file changes. ESLint stops responding. TypeScript loses track of edits. Live reload goes silent. Sometimes the editor just gets sluggish with no error shown at all.

What's Actually Happening

Linux uses inotify to watch files for changes. The kernel caps how many file watches a single user can hold — the default is 8192. VS Code plus extensions (ESLint, TypeScript server, Prettier) plus build tools like webpack or Vite can burn through that on a moderately-sized project without breaking a sweat.

Check your current limit:

cat /proc/sys/fs/inotify/max_user_watches

If it shows 8192 — or anything under 65536 — that's your culprit.

Also check the inotify instance limit (separate from watches):

cat /proc/sys/fs/inotify/max_user_instances

Default is 128. Low values here can cause a different flavour of the same crash.

Quick Fix (Until Reboot)

Raise the limit immediately without touching any config files:

sudo sysctl fs.inotify.max_user_watches=524288

The kernel applies this instantly. Then restart VS Code — it needs a fresh start to reclaim those new watch slots. Use this for quick testing; the limit resets to default after a reboot.

Permanent Fix

Two options. Pick the one that fits your setup.

Option A — Edit sysctl.conf directly

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

Option B — Drop a dedicated config file (preferred)

echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/60-vscode-watches.conf
sudo sysctl --system

A separate file in sysctl.d/ keeps the change isolated. Easy to track, easy to remove.

Verify the Fix

Confirm the new value stuck:

cat /proc/sys/fs/inotify/max_user_watches
# Should output: 524288

Restart VS Code and reopen your project. The error disappears. Extensions come back online — TypeScript picks up changes, ESLint highlights in real time, live reload kicks in again.

Want to make sure it survives a reboot?

sudo reboot
# After login:
cat /proc/sys/fs/inotify/max_user_watches

Still 524288? You're done.

Why 524288?

That's what the VS Code official Linux setup docs recommend. For most projects — including large monorepos — it's more than enough. On a memory-constrained server, 65536 or 131072 is a reasonable compromise.

Each inotify watch uses roughly 1 KB of kernel memory. So 524288 watches = ~512 MB worst-case. In practice, a busy dev machine with VS Code + Node.js + webpack might use 50,000–100,000 watches. You won't get close to the ceiling.

Still Seeing the Error?

Raised the limit and it's still complaining? A few things to dig into:

• Exclude node_modules in VS Code — open Settings and add to files.watcherExclude:

"files.watcherExclude": { "/node_modules/": true, "/.git/": true, "/dist/": true }

    This alone can cut watch usage by tens of thousands.
  
  - **Bump `max_user_instances` too** — if that value is also low, add it to the same config file:
    ```
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.d/60-vscode-watches.conf
sudo sysctl --system

• Multiple VS Code windows + extensions — every open window spawns its own set of watchers. Close the ones you're not using.
• Other tools eating watches — Dropbox, Syncthing, and webpack dev server all use inotify. Find out who's consuming the most:

Count total active inotify watches:

cat /proc//fdinfo/ 2>/dev/null | grep -c inotify

See which processes are using them:

find /proc/*/fd -lname anon_inode:inotify 2>/dev/null |
cut -d/ -f3 | xargs -I{} ps -p {} -o comm= 2>/dev/null |
sort | uniq -c | sort -rn | head -20

  

## Notes for WSL2 Users
Running VS Code via Remote-WSL and hitting this error? The fix is the same — run the `sysctl` commands inside the WSL2 Linux shell, not in Windows PowerShell. The inotify limit is a Linux kernel setting; Windows doesn't have it.