Node.js "is not allowed in NODE_OPTIONS" - Fix Disallowed Flag in CI

NODE_OPTIONS only accepts a whitelist of flags. Passing a flag Node forbids there (for example --max-semi-space-size or a non-runtime/bootstrap flag) makes Node exit immediately, before your program runs, with a clear "not allowed in NODE_OPTIONS" message.

What this error means

A job fails at process startup with <flag> is not allowed in NODE_OPTIONS, and nothing your script does runs. It often shows up after someone moves a working command-line flag into the NODE_OPTIONS env var for CI convenience.

Node output

node: --max-semi-space-size= is not allowed in NODE_OPTIONS
# or
node: --experimental-default-type is not allowed in NODE_OPTIONS

Common causes

The flag is not on the NODE_OPTIONS whitelist

Node restricts NODE_OPTIONS to a documented subset of options. Flags outside that set (some V8 flags, certain bootstrap/loader flags depending on version) are rejected when supplied via the env var.

A flag that must appear on the command line was moved to the env var

A flag that worked as node --flag script.js does not necessarily work as NODE_OPTIONS=--flag, because the env var is parsed under stricter rules.

How to fix it

Pass the restricted flag on the command line

Keep allowed flags in NODE_OPTIONS, and put disallowed ones directly on the node invocation.

Terminal / workflow

# disallowed in NODE_OPTIONS - pass it directly:
node --max-semi-space-size=64 script.js

# keep only whitelisted flags in the env var, e.g.:
NODE_OPTIONS=--max-old-space-size=4096 npm run build

Check what NODE_OPTIONS accepts for your Node

Confirm the exact flag name and that it is supported by the runner’s Node version.
Consult the Node docs for which flags NODE_OPTIONS permits in that version.
For flags Node forbids in the env var, wrap the run in a script that invokes node with the flag directly.

How to prevent it

Only put whitelisted flags in NODE_OPTIONS.
Invoke restricted flags via an explicit node command or npm script.
Verify flag support against the CI Node version.