fix: poll directories the system has no watcher left for, instead of reporting their files as removed

[alexander-akait]

Fixes #46.

The issue's title is outdated, because the error is logged now. The bug behind it is still real. When fs.watch fails with ENOSPC (fs.inotify.max_user_watches on Linux) or EMFILE, onWatcherError treats the directory as removed:

• every file in it is reported as removed, although it still exists;
• the parent watcher then sees the directory, retries, fails again, and so on: a busy loop that logs the same error over and over.

Fix: for ENOSPC/EMFILE the directory still exists, so it is not reported as removed. It is polled instead, at the interval of poll: true (5007 ms). The error is logged once per process, with a hint to raise the system limit or set WATCHPACK_POLLING. Directories that did get a watcher keep reacting at once. Other watcher errors are unchanged.

Real limit on Linux (max_user_watches = 50, 100 watched directories, every file then edited):

	main	this PR
false remove events	74	0
error lines in 7 s	7,752	1
edits reported	100/100	100/100

Tests

• test/WatcherLimit.test.js makes fs.watch throw ENOSPC for one directory. It expects no removal, a single watch attempt and log line, and the edit to be reported. It fails on main and passes here, also with WATCHPACK_POLLING=200.
• Full suite 208/208, and 204/204 with WATCHPACK_POLLING=200. npm run lint is clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_017TkBWTk3wcyUcJYDp5ZhaP

---

Generated by Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Directories that cannot be monitored because the operating system has reached its watcher limit are now checked periodically instead. Their files are no longer incorrectly reported as removed, and the fallback is logged once. This helps file-change detection continue when the system cannot create additional watchers, without repeatedly retrying the unavailable watch. Other watcher errors continue to follow their existing handling.

[changeset-bot]

🦋 Changeset detected

Latest commit: e3cb35e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
watchpack	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed]

Merging this PR will not alter performance

⚠️ 1 benchmark spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• ignored-cross-platform: regex against windows paths

✅ 36 untouched benchmarks

---

_{Comparing fix/watcher-limit-errors (e3cb35e) with main (0418015)}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 2b678b44-fc5a-41bf-b83b-bca709dcb8ba

📥 Commits

Reviewing files that changed from the base of the PR and between f8f8661 and e3cb35e.

📒 Files selected for processing: 1

• test/WatcherLimit.test.js

🚧 Files skipped from review as they are similar to previous changes: 1

• test/WatcherLimit.test.js

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

Walkthrough

When a directory watcher reports ENOSPC or EMFILE, DirectoryWatcher closes the watcher and switches to polling at a 5007 ms interval. It logs the fallback once per process and starts scanning immediately if the initial scan is complete. The change adds a public method declaration, a regression test for file change events and watcher attempts, and a patch changeset.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to e3cb3

This change makes directories that hit watcher limits fall back to polling instead of having their files reported as removed. No concrete merge-blocking risk remains in the reviewed context.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Linked Issues check		Issue [#46] directly expects an error and a nonzero process return code when the watcher limit is exceeded. The PR logs ENOSPC/EMFILE once and polls the existing directory, but `lib/DirectoryWatch…	Implement the nonzero process return-code behavior required by [#46] and add an automated test for it. If [#46] no longer requires that behavior, replace or update the direct issue link before using the narrower polling requirement.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: polling directories when watcher limits are reached instead of reporting their files as removed.
Out of Scope Changes check		The implementation, regression test, declaration update, and changeset all support the watcher-limit fix described for [#46]. They address ENOSPC/EMFILE, prevent false removal events, and switch a…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…

Full details: Out of Scope Changes check

Explanation

The implementation, regression test, declaration update, and changeset all support the watcher-limit fix described for [#46]. They address ENOSPC/EMFILE, prevent false removal events, and switch affected directories to polling. No unrelated change is established by the reviewed evidence.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files.

Full details: Linked Issues check

Explanation

Issue [#46] directly expects an error and a nonzero process return code when the watcher limit is exceeded. The PR logs ENOSPC/EMFILE once and polls the existing directory, but lib/DirectoryWatcher.js does not provide the required nonzero process return code. test/WatcherLimit.test.js verifies polling, no removal, one watch attempt, and one log line, but it does not verify the process return code.

Resolution

Implement the nonzero process return-code behavior required by [#46] and add an automated test for it. If [#46] no longer requires that behavior, replace or update the direct issue link before using the narrower polling requirement.

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 638a6e40-2343-45c3-8fe6-9bbeee653e5f

📥 Commits

Reviewing files that changed from the base of the PR and between 0418015 and f8f8661.

📒 Files selected for processing: 4

• .changeset/watcher-limit-polling.md
• lib/DirectoryWatcher.js
• test/WatcherLimit.test.js
• types/DirectoryWatcher.d.ts

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.72%. Comparing base (0418015) to head (e3cb35e).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #359      +/-   ##
==========================================
+ Coverage   92.65%   92.72%   +0.07%     
==========================================
  Files           8        8              
  Lines        1389     1403      +14     
  Branches      416      420       +4     
==========================================
+ Hits         1287     1301      +14     
  Misses         96       96              
  Partials        6        6              

Flag	Coverage Δ
integration	92.72% <100.00%> (+0.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.