How to fix Error: ENOSPC: System limit for number of file watchers reached in Git

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 298 views

This error occurs when Linux runs out of inotify file watchers. Development tools like VS Code, webpack, and Git use inotify to monitor file changes in real-time. The default limit is often too low for large projects. The fix is to increase the inotify watches limit in your system configuration.

Quick fix

Fixes ENOSPC

# Check the current maximum number of inotify watches
cat /proc/sys/fs/inotify/max_user_watches

# Check current usage (approximate)
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l

# More detailed view of inotify usage per process
for pid in $(pgrep -u $USER); do
  count=$(find /proc/$pid/fd -lname 'anon_inode:inotify' 2>/dev/null | wc -l)
  if [ "$count" -gt 0 ]; then
    echo "$count $(cat /proc/$pid/comm 2>/dev/null)"
  fi
done | sort -rn | head -20
  1. Check the current inotify limit
  2. Temporarily increase the limit (testing)
  3. Permanently increase the inotify limit
  4. Restart affected applications
git — error
# Check the current maximum number of inotify watches
cat /proc/sys/fs/inotify/max_user_watches
# Check current usage (approximate)
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l
# More detailed view of inotify usage per process
for pid in $(pgrep -u $USER); do
  count=$(find /proc/$pid/fd -lname 'anon_inode:inotify' 2>/dev/null | wc -l)
  if [ "$count" -gt 0 ]; then
    echo "$count $(cat /proc/$pid/comm 2>/dev/null)"
  fi
done | sort -rn | head -20
Error: ENOSPC: System limit for number of file watchers reached

What this error means

The "ENOSPC: System limit for number of file watchers reached" error indicates that your Linux system has exhausted its available inotify watches. Despite the "ENOSPC" code (which typically means "no space left on device"), this error is about running out of inotify watch slots, not disk space. Inotify is a Linux kernel subsystem that allows applications to monitor filesystem events in real-time, such as file modifications, creations, and deletions. Each file or directory being watched consumes one inotify watch. The kernel enforces a system-wide limit on the total number of watches to prevent resource exhaustion. Modern development workflows are particularly demanding on inotify: - **IDEs and editors** (VS Code, IntelliJ, Sublime) watch project files for changes - **Build tools** (webpack, Vite, esbuild) watch source files for hot reloading - **Version control** (Git, especially through IDE integrations) monitors repository state - **Node.js file watchers** (nodemon, chokidar) watch for application restarts - **Docker and container tools** may watch for file sync When you hit this limit, any application trying to create new file watches will fail with ENOSPC. This commonly manifests during `git status`, IDE startup, or when running a development server with hot reload.

Typical symptoms

  • Git commands fail with 'ENOSPC: System limit for number of file watchers reached'
  • VS Code or other IDEs show warnings about being unable to watch files
  • Webpack/Vite hot reload stops detecting file changes
  • nodemon or other file watchers stop responding to changes
  • The error appears suddenly after opening multiple large projects
  • npm/yarn watch commands fail during development
  • Jest watch mode fails to start or stops detecting changes
  • Docker development environments fail to sync file changes

Common causes

  1. The default inotify watch limit (typically 8192 or 65536) is too low for your workflow
  2. Multiple development tools are running simultaneously, each consuming watches
  3. Large projects with many files (especially node_modules) exhaust available watches
  4. VS Code or IDE watching entire project directories including node_modules
  5. Multiple browser tabs with development servers holding file watchers
  6. Running several projects concurrently in different terminals or windows
  7. Docker bind mounts requiring inotify watches for file synchronization
  8. File sync tools like Dropbox or Google Drive consuming watches in the background

How to fix "Error: ENOSPC: System limit for number of file watchers reached"

1Check the current inotify limit

First, check your current inotify watches limit and how many are in use:

bash
# Check the current maximum number of inotify watches
cat /proc/sys/fs/inotify/max_user_watches

# Check current usage (approximate)
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l

# More detailed view of inotify usage per process
for pid in $(pgrep -u $USER); do
  count=$(find /proc/$pid/fd -lname 'anon_inode:inotify' 2>/dev/null | wc -l)
  if [ "$count" -gt 0 ]; then
    echo "$count $(cat /proc/$pid/comm 2>/dev/null)"
  fi
done | sort -rn | head -20

The default limit varies by distribution:
- Ubuntu/Debian: 8192 (older) to 65536 (newer)
- Fedora/RHEL: 8192
- Arch Linux: 8192

For development work, you typically need 100,000 to 500,000 watches.

2Temporarily increase the limit (testing)

Before making permanent changes, test if increasing the limit fixes your issue:

bash
# Temporarily increase to 524288 (requires sudo)
sudo sysctl fs.inotify.max_user_watches=524288

# Verify the change
cat /proc/sys/fs/inotify/max_user_watches

This change is temporary and will reset on reboot. If this fixes your problem, proceed to make the change permanent.

Note: You may need to restart the application that was failing (VS Code, webpack, etc.) for it to successfully acquire new watches.

3Permanently increase the inotify limit

To make the change persist across reboots, add it to your sysctl configuration:

Option 1: Create a new sysctl config file (recommended)

bash
# Create a new config file
echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/50-inotify.conf

# Apply the change immediately
sudo sysctl -p /etc/sysctl.d/50-inotify.conf

Option 2: Add to the main sysctl.conf

bash
# Append to sysctl.conf
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf

# Apply the change
sudo sysctl -p

Verify the permanent change:

bash
# Should show 524288
cat /proc/sys/fs/inotify/max_user_watches

# Verify it's in the config
grep max_user_watches /etc/sysctl.d/*.conf /etc/sysctl.conf 2>/dev/null

The value 524288 (512K) is sufficient for most development workflows. For extremely large monorepos, you might use 1048576 (1M).

4Restart affected applications

After increasing the limit, restart the applications that were failing:

For VS Code:
1. Close all VS Code windows completely
2. Optionally run code --extensions-dir /tmp/test to verify it works
3. Reopen VS Code normally

For terminal-based watchers:

bash
# Restart your development server
# Ctrl+C to stop, then restart
npm run dev
# or
yarn dev

For webpack/Vite:

bash
# Stop any running dev servers
pkill -f webpack
pkill -f vite

# Restart your build tool
npm run watch

For Git integration issues:

bash
# Test Git directly
git status

# If using Git in an IDE, restart the IDE

Applications that failed to acquire watches when the limit was reached will now succeed.

5Reduce inotify usage (optional optimization)

If you prefer not to increase the limit significantly, or if you're on a system where you can't change it, reduce watch usage:

Exclude node_modules in VS Code:
Add to .vscode/settings.json:

json
{
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/dist/**": true,
    "**/build/**": true,
    "**/.next/**": true
  }
}

Configure webpack to ignore node_modules:

javascript
// webpack.config.js
module.exports = {
  watchOptions: {
    ignored: /node_modules/,
  },
};

Use polling instead of inotify (last resort):

bash
# For webpack
CHOKIDAR_USEPOLLING=true npm run dev

# Or in webpack config
watchOptions: {
  poll: 1000,
  ignored: /node_modules/
}

Polling uses more CPU but doesn't consume inotify watches.

6Handle WSL-specific issues

If you're using Windows Subsystem for Linux (WSL), there are additional considerations:

WSL2 has its own inotify limits:

bash
# Check WSL version
wsl --list --verbose

# Inside WSL, increase the limit the same way
echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/50-inotify.conf
sudo sysctl -p /etc/sysctl.d/50-inotify.conf

Cross-filesystem watching issues:
When watching files on the Windows filesystem from WSL (/mnt/c/), inotify doesn't work reliably. For best results:
- Keep your project files inside the Linux filesystem (~/projects/ not /mnt/c/)
- Use VS Code with the Remote-WSL extension

WSL1 specific:
WSL1 has limited inotify support. Consider upgrading to WSL2 for better file watching.

Restart WSL if changes don't take effect:

powershell
# From PowerShell (as admin)
wsl --shutdown
# Then reopen your WSL terminal

Advanced notes

Understanding Inotify Resource Limits:

Linux provides three inotify-related sysctl parameters:

| Parameter | Description | Default |
|-----------|-------------|---------|
| max_user_watches | Max watches per user | 8192-65536 |
| max_user_instances | Max inotify instances per user | 128 |
| max_queued_events | Max events in queue | 16384 |

Most commonly, max_user_watches is the bottleneck. Each watch consumes approximately 1KB of kernel memory (on 64-bit systems), so 524288 watches use about 512MB of kernel memory.

Memory Impact Calculation:

bash
# Each watch uses approximately 1080 bytes on 64-bit systems
# 524288 watches * 1080 bytes = ~540MB maximum

# However, only used watches consume memory
# Check current memory usage for inotify (approximate)
cat /proc/meminfo | grep -i slab

Debugging Which Processes Use the Most Watches:

bash
#!/bin/bash
# List processes by inotify watch usage

echo "Counting inotify watches per process..."

for pid in $(pgrep -u $USER); do
    watches=$(find /proc/$pid/fdinfo -type f -exec grep -c inotify {} + 2>/dev/null | awk '{sum+=$1}END{print sum}')
    if [ "$watches" != "" ] && [ "$watches" -gt 0 ]; then
        comm=$(cat /proc/$pid/comm 2>/dev/null)
        echo "$watches $pid $comm"
    fi
done | sort -rn | head -20

Why Git Triggers This Error:

Git itself rarely exhausts inotify watches directly. The error typically occurs because:
1. IDE Git integrations watch the entire repository for changes
2. Multiple tools compete for the same limited pool of watches
3. The .git directory itself contains many files that may be watched

System-Wide vs. User-Specific Limits:

The max_user_watches limit is per-user, not system-wide. If you have multiple users running development tools, each has their own allocation. Conversely, all processes for a single user share that user's allocation.

Container Considerations:

Docker containers share the host kernel's inotify limits. If you're running development containers, you need to increase the limit on the host, not in the container:

bash
# On the Docker host
sudo sysctl -w fs.inotify.max_user_watches=524288

For Docker Desktop on Mac/Windows, the limit is managed by the Linux VM and is typically already high enough.

Alternative: Use fswatch on macOS:

If you're on macOS (where inotify doesn't exist), you use FSEvents instead, which doesn't have the same limits. However, if you're running Linux containers or VMs from macOS, those environments still use inotify.

Systemd and Modern Distributions:

Some modern distributions use systemd's resource management. If sysctl changes don't persist, check for systemd overrides:

bash
# Check for systemd overrides
systemctl cat systemd-sysctl.service

# Create an override if needed
sudo systemctl edit systemd-sysctl.service

Security Considerations:

Increasing inotify limits doesn't pose a significant security risk. The limits exist primarily to prevent resource exhaustion (denial of service by a runaway process). For development workstations, higher limits are safe and expected.

Frequently asked questions

What does "ENOSPC" mean?
The "ENOSPC: System limit for number of file watchers reached" error indicates that your Linux system has exhausted its available inotify watches. Despite the "ENOSPC" code (which typically means "no space left on device"), this error is about running out of inotify watch slots, not disk space. Inotify is a Linux kernel subsystem that allows applications to monitor filesystem events in real-time, such as file modifications, creations, and deletions.
How do I fix "ENOSPC"?
This error occurs when Linux runs out of inotify file watchers. Development tools like VS Code, webpack, and Git use inotify to monitor file changes in real-time. The default limit is often too low for large projects. The fix is to increase the inotify watches limit in your system configuration.
What causes "ENOSPC"?
The default inotify watch limit (typically 8192 or 65536) is too low for your workflow Multiple development tools are running simultaneously, each consuming watches Large projects with many files (especially node_modules) exhaust available watches
Is the "ENOSPC" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading