Skip to content

doc: clarify FileHandle error handling - #63719

Open
bobu-putheeckal wants to merge 1 commit into
nodejs:mainfrom
bobu-putheeckal:codex-doc-51135
Open

doc: clarify FileHandle error handling#63719
bobu-putheeckal wants to merge 1 commit into
nodejs:mainfrom
bobu-putheeckal:codex-doc-51135

Conversation

@bobu-putheeckal

@bobu-putheeckal bobu-putheeckal commented Jun 2, 2026

Copy link
Copy Markdown

Fixes: #51135

This clarifies that filehandle.close() and filehandle.stat() promises may reject when the underlying file system operation fails, and points readers to Common System Errors for code values.

Evidence checked:

  • FileHandle.prototype.stat() calls fsCall(fstat, this, options) in lib/internal/fs/promises.js.
  • fstat() uses binding.fstat(..., kUsePromises) and routes binding failures through handleErrorFromBinding.
  • FileHandle::ClosePromise() in src/node_file.cc documents that the close promise rejects with a UVException if closing the fd fails.
  • The linked issue includes a maintainer example showing filehandle.stat() rejecting with EBADF after the handle is closed.

Validation:

  • git diff --check
  • node tools/lint-md/lint-md.mjs doc/api/fs.md
  • npx -q core-validate-commit --no-validate-metadata --tap HEAD

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module. labels Jun 2, 2026
Fixes: nodejs#51135
Signed-off-by: Bob Put <bobu.work@gmail.com>
Comment thread doc/api/fs.md
Comment on lines +245 to +246
The promise is rejected if closing the file handle fails. In case of an error,
the error's `code` will be one of [Common System Errors][].

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The linked section is explicitly non-exhaustive and does not include EBADF, which is one failure filehandle.stat() can return. We should avoid promising that every code appears there.

Suggested change
The promise is rejected if closing the file handle fails. In case of an error,
the error's `code` will be one of [Common System Errors][].
The promise is rejected if closing the file handle fails. The error's `code`
identifies the platform-dependent system error; see [Common System Errors][]
for examples.

Please make the equivalent change in the filehandle.stat() occurrence below as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to Node.js documentation. fs Issues and PRs related to file-system APIs and the fs module.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

It's not clear if FileHandle close() and stat() can fail

3 participants