Fix 'Limit of File Watchers Reached' in Gatsby on Ubuntu or Debian

This problem is caused by the way Gatsby.js works, generates static files, and optimizes photos, which easily exceeds the defined Listen limit for the number of files that the Linux OS monitors per directory.

Namely, the Linux OS uses Listen inotify to monitor file changes in directories. Therefore, it is not uncommon to encounter a system limit in the number of files you can monitor. For example, the inotify limit on Ubuntu Lucid (64bit) is set to 8192.

What is the current limit of your system you can find out with command:

cat /proc/sys/fs/inotify/max_user_watches

When the defined limit is not sufficient to track file changes in the directory, you must increase the limit for Listen to work properly.

You can set a new temporary limit with the command:

sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl -p

If you want to permanently change the Listen limit, use the command:

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

Broader context: This inotify limit issue isn’t exclusive to Gatsby — it affects any tool that relies on file watching: webpack dev server, nodemon, VS Code, and most frontend build tools. The sysctl -w approach above changes the limit immediately but resets on reboot. Adding the setting to /etc/sysctl.conf makes it permanent across restarts. Be careful not to set the value too high — each watch uses ~1 KB of kernel memory, so a value of 524288 consumes roughly 500 MB of non-swappable kernel memory.

If you still have problems with Listen check the values max_queued_events and max_user_instances.