Introduction

The Linux inotify API allows applications to monitor filesystem events. Each watched file or directory consumes one watch handle from the kernel pool limited by fs.inotify.max_user_watches (default 8192). Modern development tools that watch entire project trees (webpack, gulp, nodemon, VS Code) can exhaust this limit quickly, causing file change detection to fail silently.

Symptoms

  • webpack: Error: ENOSPC: System limit for number of file watchers reached
  • nodemon: Error: watch ENOSPC
  • VS Code: The workspace contains more than 8192 files, watch failed
  • dmesg shows inotify_add_watch: too many open files
  • Applications stop detecting file changes without explicit errors
  • cat /proc/sys/fs/inotify/max_user_watches shows 8192

Common Causes

  • Large project directories with thousands of files (node_modules, vendor/)
  • Multiple file watchers running simultaneously
  • Default max_user_watches of 8192 too low for modern development
  • Watcher recursively monitoring directories with many subdirectories
  • Docker bind mounts creating additional watch entries

Step-by-Step Fix

  1. 1.Check current inotify watch usage:
  2. 2.```bash
  3. 3.cat /proc/sys/fs/inotify/max_user_watches
  4. 4.# Count current watches in use
  5. 5.sudo find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l
  6. 6.# See which processes hold watches
  7. 7.for pid in $(pgrep -f "node|webpack|vscode"); do
  8. 8.count=$(ls -la /proc/$pid/fd 2>/dev/null | grep -c inotify)
  9. 9.[ "$count" -gt 0 ] && echo "PID $pid: $count watches"
  10. 10.done
  11. 11.`
  12. 12.Increase the inotify watch limit:
  13. 13.```bash
  14. 14.# Temporary (until reboot)
  15. 15.sudo sysctl -w fs.inotify.max_user_watches=524288
  16. 16.# Verify
  17. 17.cat /proc/sys/fs/inotify/max_user_watches
  18. 18.`
  19. 19.Make the change persistent:
  20. 20.```bash
  21. 21.echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
  22. 22.echo "fs.inotify.max_queued_events=16384" | sudo tee -a /etc/sysctl.conf
  23. 23.echo "fs.inotify.max_user_instances=1024" | sudo tee -a /etc/sysctl.conf
  24. 24.sudo sysctl -p
  25. 25.`
  26. 26.Optimize watcher exclude patterns (webpack example):
  27. 27.```javascript
  28. 28.// webpack.config.js
  29. 29.module.exports = {
  30. 30.watchOptions: {
  31. 31.ignored: /node_modules|\.git|\.svn|vendor/
  32. 32.}
  33. 33.};
  34. 34.`
  35. 35.Configure VS Code to exclude directories:
  36. 36.```json
  37. 37.// settings.json
  38. 38.{
  39. 39."files.watcherExclude": {
  40. 40."/node_modules/": true,
  41. 41."/.git/objects/": true,
  42. 42."/dist/": true
  43. 43.}
  44. 44.}
  45. 45.`
  46. 46.Verify the fix by restarting the affected application:
  47. 47.```bash
  48. 48.# Restart webpack
  49. 49.npm run dev
  50. 50.# Check no ENOSPC errors in output
  51. 51.`

Prevention

  • Set max_user_watches=524288 as a baseline on development machines
  • Exclude node_modules, .git, vendor, dist from file watchers
  • Use polling-based watching (watchOptions.poll) as a fallback for network filesystems
  • Monitor inotify usage in team onboarding documentation
  • Use inotifywatch from inotify-tools to profile watch usage