GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — doc: document --trace-promises by tomass22 · Pull Request #65199 · nodejs/node

Conversation

@tomass22

@tomass22 tomass22 commented Aug 10, 2026

Copy link
Copy Markdown

--trace-promises has been available since v21.5.0 (backported to v20.12.0 in
#50899) but has never been documented.

  • Registered in src/node_options.cc with kAllowedInEnvvar, so it is also
    usable through NODE_OPTIONS
  • Implemented in src/env.cc as Environment::TracePromises, installed as an
    isolate-wide promise hook in src/node.cc
  • Absent from both doc/api/cli.md and doc/node.1

When the flag landed, it was added to the "intentionally undocumented options"
list in test/parallel/test-process-env-allowed-flags-are-documented.js instead
of being documented:

assert(undocumented.delete('--trace-promises'));
assert(undocumented.delete('--no-trace-promises'));

I believe that was an oversight rather than a deliberate decision. The other
entries in that list fall into two groups:

  • legacy no-ops kept for compatibility — --experimental-fetch,
    --experimental-global-webcrypto, --experimental-report,
    --experimental-worker, --napi-modules, --es-module-specifier-resolution
  • internal-only debugging switches — --debug-arraybuffer-allocations,
    --verify-base-objects, --node-snapshot

--trace-promises is neither. It is a user-facing diagnostic flag in the same
family as --trace-env, --trace-uncaught and --trace-warnings, all of which
are documented.

This PR:

  • documents the flag in doc/api/cli.md, both as a ### section and in the
    NODE_OPTIONS allow-list
  • regenerates doc/node.1 with make node.1
  • removes the two exemptions from the test

No new test is needed. Removing the exemptions makes the existing
test-process-env-allowed-flags-are-documented test cover this flag — it fails
without the documentation change.

Refs: #50899

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

daeyeon reacted with hooray emoji
All reactions
  • 🎉 1 reaction
@tomass22
doc: document --trace-promises
58f3596
`--trace-promises` has been available since v21.5.0 but was never added
to the CLI documentation. Instead it was added to the list of
intentionally undocumented options in
test/parallel/test-process-env-allowed-flags-are-documented.js.

Unlike the other entries in that list, which are either legacy no-ops or
internal-only debugging switches, `--trace-promises` is a user-facing
diagnostic flag that is allowed in NODE_OPTIONS, and its siblings
`--trace-env`, `--trace-uncaught` and `--trace-warnings` are all
documented.

Document it in doc/api/cli.md, regenerate doc/node.1 accordingly, and
drop the two exemptions from the test.

Assisted-by: Claude Opus 5 (1M context)
Signed-off-by: tomass22 <[email protected]>
@nodejs-github-bot nodejs-github-bot added the needs-ci PRs that need a full CI run. label Aug 10, 2026
daltino

This comment was marked as resolved.

Sign in to view

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

Reviewers

1 more reviewer
@daltino daltino daltino left review comments
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

needs-ci PRs that need a full CI run.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@tomass22 @daltino @nodejs-github-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.