Skip to content

fix(tui): pass --expose-gc as node argv instead of NODE_OPTIONS - #21711

Closed
YarrowQiao wants to merge 1 commit into
NousResearch:mainfrom
YarrowQiao:fix/tui-expose-gc-not-allowed-in-node-options
Closed

fix(tui): pass --expose-gc as node argv instead of NODE_OPTIONS#21711
YarrowQiao wants to merge 1 commit into
NousResearch:mainfrom
YarrowQiao:fix/tui-expose-gc-not-allowed-in-node-options

Conversation

@YarrowQiao

Copy link
Copy Markdown
Contributor

Summary

hermes --tui fails to start on every modern Node release with:

node: --expose-gc is not allowed in NODE_OPTIONS

_launch_tui() was appending --expose-gc to NODE_OPTIONS before spawning the TUI. Node restricts NODE_OPTIONS to a small allowlist (so anything able to set env vars on a node child can't unilaterally enable arbitrary capabilities) — --expose-gc is not on that list and never has been. It must be passed as a direct argv flag.

The intent (manual GC for long sessions to avoid fatal-OOM on large transcripts / reasoning blobs) is preserved by inserting --expose-gc directly into the node argv inside _make_tui_argv() — same effect, but actually allowed.

--max-old-space-size=8192 stays in NODE_OPTIONS because it is allowlisted, and keeping it there means downstream node spawns inherit the same heap cap without re-threading the flag through every spawn site.

The dev paths (tsx src/entry.tsx and npm start fallback) are intentionally left alone — they don't accept node flags directly, and the production dist path is the one users actually hit via hermes --tui. The shebang in ui-tui/src/entry.tsx already documents the intended flags for direct execution.

Repro (before fix)

$ hermes --tui
/usr/bin/node: --expose-gc is not allowed in NODE_OPTIONS

Test plan

  • hermes --tui starts without the --expose-gc is not allowed error on Node v18.20.8 (Linux/WSL2)
  • import hermes_cli.main succeeds (no syntax regressions)
  • Manual smoke: long-running TUI session still has 8GB heap and a callable global.gc()

Node refuses to start when NODE_OPTIONS contains --expose-gc:

    node: --expose-gc is not allowed in NODE_OPTIONS

NODE_OPTIONS is restricted to a small allowlist of flags that are safe
to inject via env (since any process able to set env vars on a node
child could otherwise enable arbitrary capabilities). --expose-gc is
not on that list and never has been -- it must be passed as a direct
CLI flag.

_launch_tui() was appending --expose-gc to NODE_OPTIONS before spawning
the TUI's node process, which made `hermes --tui` fail to start on
every modern node release. The intent (manual GC for long sessions to
avoid fatal-OOM) is preserved by inserting --expose-gc directly into
the node argv in _make_tui_argv() -- same effect, but actually allowed.

--max-old-space-size=8192 stays in NODE_OPTIONS: it *is* allowlisted,
and keeping it there means downstream node spawns inherit the same
heap cap without having to re-thread the flag through every spawn site.

The dev paths (`tsx src/entry.tsx` and `npm start` fallback) are left
alone -- they don't accept node flags directly, and the production
dist path is the one users actually hit via `hermes --tui`.

Repro before fix:

    $ hermes --tui
    /usr/bin/node: --expose-gc is not allowed in NODE_OPTIONS
@alt-glitch alt-glitch added type/bug Something isn't working P2 Medium — degraded but workaround exists comp/tui Terminal UI (ui-tui/ + tui_gateway/) comp/cli CLI entry point, hermes_cli/, setup wizard labels May 8, 2026
@alt-glitch

Copy link
Copy Markdown
Collaborator

Duplicate of #17200 which addresses the same --expose-gc NODE_OPTIONS issue (fix for #17187).

@teknium1

Copy link
Copy Markdown
Contributor

Merged via PR #29998 — your commit was cherry-picked onto current main with your authorship preserved in git log (2ea7cf2). Added a small sibling-site fix on top (wheel-bundled launch path was missing --expose-gc too). Thanks for the clean fix and the great commit message explaining the NODE_OPTIONS allowlist rationale! Closes #17187 too.

@teknium1 teknium1 closed this May 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/cli CLI entry point, hermes_cli/, setup wizard comp/tui Terminal UI (ui-tui/ + tui_gateway/) P2 Medium — degraded but workaround exists type/bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants