How to fix Error: ENOSPC: no space left on device (fs.watch ran out of capacity) in Node.js

What this error means

This error indicates that Node.js's fs.watch() function has exhausted the operating system's capacity to monitor file system changes. Unlike disk space issues, this refers to the system limit on inode watchers or file descriptor watches. On Linux systems, each watched file consumes a slot in the kernel's inotify watch limit (controlled by /proc/sys/fs/inotify/max_user_watches). When this limit is reached, fs.watch() fails with ENOSPC. On macOS and Windows, similar limitations exist through their respective file system event APIs (FSEvents and ReadDirectoryChangesW). This commonly occurs in development environments with build tools, IDE watchers, or applications monitoring large directory trees.

Typical symptoms

• fs.watch() throws ENOSPC error when adding new file watchers
• Build tools (webpack, vite, Next.js dev server) fail to start or freeze
• IDE watchers stop working without error messages
• Application crashes after watching a certain number of files
• Error appears when running multiple watchers simultaneously
• Problem occurs specifically on Linux systems first

Common causes

1. Linux inotify watch limit (/proc/sys/fs/inotify/max_user_watches) is too low for the number of files being monitored
2. Multiple Node.js processes or watchers all competing for the same system inotify limit
3. Watching large project directories or node_modules with many nested files
4. File watcher not properly cleaning up watches after deletion
5. System-wide resource exhaustion from other applications also using inotify
6. macOS or Windows file system event API hitting internal limits

How to fix "Error: ENOSPC: no space left on device (fs.watch ran out of capacity)"

cat /proc/sys/fs/inotify/max_user_watches

# Check current value
sudo sysctl fs.inotify.max_user_watches

# Set it to a higher value (e.g., 100000)
sudo sysctl -w fs.inotify.max_user_watches=100000

# Edit the sysctl configuration
sudo nano /etc/sysctl.conf

# Add or update this line
fs.inotify.max_user_watches=100000

# Apply the changes
sudo sysctl -p

RUN echo fs.inotify.max_user_watches=100000 | tee -a /etc/sysctl.conf

docker run --sysctl fs.inotify.max_user_watches=100000 your-image

// webpack.config.js
module.exports = {
  watchOptions: {
    ignored: ['node_modules', '.git', 'dist', 'build'],
    aggregateTimeout: 300,
    poll: false,
  },
};

// next.config.js
module.exports = {
  onDemandEntries: {
    maxInactiveAge: 25 * 1000,
    pagesBufferLength: 5,
  },
};

// vite.config.js
export default {
  server: {
    watch: {
      ignored: ['node_modules', '.git', 'dist'],
      usePolling: false,
    },
  },
};

// .parcelrc
{
  "watchIgnore": ["node_modules", ".git", "dist"],
}

// For webpack
watchOptions: {
  poll: 1000, // Poll every 1000ms instead of using inotify
  aggregateTimeout: 300,
}

// For custom fs.watch usage
fs.watch(path, { recursive: true }, (eventType, filename) => {
  // Your handler
});

// Fallback pattern
const watcher = fs.watch(path, (eventType, filename) => {
  // Handler
});

watcher.on('error', (err) => {
  if (err.code === 'ENOSPC') {
    console.log('Falling back to fs.watchFile (polling)');
    fs.watchFile(path, { interval: 1000 }, (curr, prev) => {
      // Your polling handler
    });
  }
});

// Generic watch with exclusions
function watchDirectory(dir, callback) {
  const ignoredDirs = new Set([
    'node_modules',
    '.git',
    '.next',
    'dist',
    'build',
    '.cache',
    'coverage',
    '.pytest_cache',
  ]);

  function watch(path) {
    const basename = require('path').basename(path);
    if (ignoredDirs.has(basename)) {
      return;
    }

    fs.watch(path, { recursive: true }, callback);
  }

  watch(dir);
}

// In your lerna.json or package.json workspaces
{
  "workspaces": {
    "packages": ["packages/*/src"],
    "ignoreChanges": ["**/node_modules/**", "**/*.test.ts", "**/dist/**"]
  }
}

# Check soft limit
ulimit -n

# Increase soft limit for current session
ulimit -n 10240

# Make permanent (add to ~/.zshrc or ~/.bash_profile)
ulimit -n 10240

const watchPath = (path, callback) => {
  fs.watch(path, callback).on('error', (err) => {
    if (err.code === 'ENOSPC' || err.code === 'EMFILE') {
      console.log('Using fs.watchFile fallback...');
      fs.watchFile(path, { interval: 1000 }, callback);
    }
  });
};

Advanced notes

# Set limit for a specific process
prlimit --nofile=10240 --nproc=10240 npm start

# Show inotify usage per process on Linux
find /proc -name wd_list -exec wc -l {} \;

# Or use lsof to see all watches
lsof | grep inotify

Frequently asked questions

What does "ENOSPC" mean?

watch() function has exhausted the operating system's capacity to monitor file system changes. Unlike disk space issues, this refers to the system limit on inode watchers or file descriptor watches. On Linux systems, each watched file consumes a slot in the kernel's inotify watch limit (controlled by /proc/sys/fs/inotify/max_user_watches).

How do I fix "ENOSPC"?

This error occurs when Node.js fs.watch() reaches the system limit on file descriptors or inode watchers. The file watching subsystem cannot monitor additional files because the system has exhausted its available watching capacity.

What causes "ENOSPC"?

Linux inotify watch limit (/proc/sys/fs/inotify/max_user_watches) is too low for the number of files being monitored Multiple Node.js processes or watchers all competing for the same system inotify limit Watching large project directories or node_modules with many nested files

Is the "ENOSPC" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Error: EMFILE: too many open files, watch

  EMFILE: too many open files, watch

  MEDIUM

• Error: EPERM: operation not permitted, symlink 'target' -> 'link'

  EPERM: operation not permitted, symlink on Windows (admin required)

  HIGH

• Error: Failed to write heap snapshot (disk space or permission)

  Failed to write heap snapshot (disk space or permission)

  MEDIUM

• Error: recursive option not supported in this Node.js version

  How to fix "Error: recursive option not supported in this Node.js version" in Node.js

  MEDIUM

• Error: zlib error Z_DATA_ERROR (corrupted compressed data)

  Z_DATA_ERROR: Corrupted compressed data

  MEDIUM

• Error: Could not find package.json in current directory (npm module resolution)

  How to fix "Could not find package.json in current directory" in Node.js

  MEDIUM

Official resources & further reading

• 📚Node.js Official Documentation
• 📖
  Node.js fs.watch() Documentation(Official Docs)
• 📖
  Linux inotify(7) Manual Page(Official Docs)
• 🐙
  Create React App - ENOSPC Error Discussion(GitHub)
• 🔗
  Webpack Watch Configuration
• 🔗
  Vite Server Watch Configuration