Introduction

On Linux, VS Code uses the inotify system to watch files for changes. When the number of watched files exceeds the system's max_user_watches limit, VS Code shows an error and file watching stops working:

bash
Visual Studio Code is unable to watch for file changes in this large workspace
(error: ENOSPC: System limit for number of file watchers reached)

This breaks auto-save, auto-refresh, Git change detection, and task runners.

Symptoms

  • Error notification about "System limit for number of file watchers reached"
  • File changes are not detected (no auto-refresh in explorer)
  • Git changes do not appear in the Source Control panel
  • Auto-save stops working
  • Task runners do not trigger on file changes

Common Causes

  • Default fs.inotify.max_user_watches is 8192 (too low for large projects)
  • Large node_modules directory with thousands of files being watched
  • Multiple VS Code instances each consuming watch slots
  • Project with many small files (e.g., microservices monorepo)
  • Other applications (Webpack, nodemon) also using inotify watches

Step-by-Step Fix

  1. 1.Check current inotify watch limit:
  2. 2.```bash
  3. 3.cat /proc/sys/fs/inotify/max_user_watches
  4. 4.# Default is usually 8192
  5. 5.`
  6. 6.Increase the limit permanently. Add to /etc/sysctl.conf:
  7. 7.`
  8. 8.fs.inotify.max_user_watches=524288
  9. 9.fs.inotify.max_user_instances=512
  10. 10.`
  11. 11.Apply the changes:
  12. 12.```bash
  13. 13.sudo sysctl -p
  14. 14.`
  15. 15.Verify the new limit:
  16. 16.```bash
  17. 17.cat /proc/sys/fs/inotify/max_user_watches
  18. 18.# Should show 524288
  19. 19.`
  20. 20.Exclude large directories from file watching in VS Code. In .vscode/settings.json:
  21. 21.```json
  22. 22.{
  23. 23."files.watcherExclude": {
  24. 24."/.git/objects/": true,
  25. 25."/.git/subtree-cache/": true,
  26. 26."/node_modules/*/": true,
  27. 27."/dist/": true,
  28. 28."/build/": true,
  29. 29."/vendor/": true
  30. 30.},
  31. 31."search.exclude": {
  32. 32."**/node_modules": true,
  33. 33."**/bower_components": true
  34. 34.}
  35. 35.}
  36. 36.`
  37. 37.Check how many watches VS Code is using:
  38. 38.```bash
  39. 39.find /proc/*/fd -user $(whoami) -lname 'anon_inode:inotify' 2>/dev/null | wc -l
  40. 40.`

Prevention

  • Set fs.inotify.max_user_watches to at least 524288 on all development machines
  • Include the sysctl configuration in your development environment setup scripts
  • Always exclude node_modules, dist, build, and .git from file watching
  • Use files.watcherInclude to explicitly watch only the directories you need
  • Monitor watch usage on large projects and adjust exclusions accordingly
  • For Docker development, ensure the inotify limit is set in the container as well
  • Document the required sysctl settings in your project's development setup guide
  • Consider using polling-based file watching ("files.watcherExclude": {} with #parcel watcher) for very large workspaces