Skip to content

doc: fix fs.watch overflow option accepted value - #65174

Open
arhxam wants to merge 1 commit into
nodejs:mainfrom
arhxam:doc-fs-watch-overflow
Open

doc: fix fs.watch overflow option accepted value#65174
arhxam wants to merge 1 commit into
nodejs:mainfrom
arhxam:doc-fs-watch-overflow

Conversation

@arhxam

@arhxam arhxam commented Aug 9, 2026

Copy link
Copy Markdown

Description

The overflow option for fs.watch() / fsPromises.watch() is
documented as accepting 'ignore' or 'throw', but the implementation
validates the value against ['ignore', 'error'] in
lib/internal/fs/watchers.js:

validateOneOf(overflow, 'options.overflow', ['ignore', 'error']);

So a user who follows the docs and passes overflow: 'throw' gets an
error instead of the described behavior:

const { watch } = require('node:fs/promises');
const it = watch('.', { overflow: 'throw' });
await it.next();
// -> TypeError [ERR_INVALID_ARG_VALUE]: The property 'options.overflow'
//    must be one of: 'ignore', 'error'. Received 'throw'

The value that is actually accepted, 'error', throws
ERR_FS_WATCH_QUEUE_OVERFLOW on overflow, which matches the documented
"throw an exception" behavior. This updates the documentation to use
'error'. Documentation-only change; 'throw' and 'error' are the
same length so no reflowing is needed.

The `overflow` option for `fs.watch()` and `fsPromises.watch()` is
documented as accepting `'ignore'` or `'throw'`, but the implementation
validates against `['ignore', 'error']` in
lib/internal/fs/watchers.js. Passing the documented `'throw'` value
therefore throws `ERR_INVALID_ARG_VALUE`. Update the documentation to
use `'error'`, the value that is actually accepted.

Signed-off-by: Arham Wani <arhamwani765@gmail.com>
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. labels Aug 9, 2026
@daeyeon daeyeon added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Aug 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants