Node Build Flag Rejected as "bad option" in CI - Fix the Build Invocation

By Kaveh Alemi·Latchkey

A build that injects extra Node flags (heap size, loaders, experimental features) fails immediately when the runner Node does not recognize one of them.

What this error means

A build step exits at once with node: bad option: <flag>, because a build script or NODE_OPTIONS passes a flag the CI Node version rejects.

> cross-env NODE_OPTIONS='--max-old-space-size=4096 --loader ts-node/esm' vite build

node: bad option: --loader ts-node/esm
$ exit status 9

Common causes

A removed or renamed flag in NODE_OPTIONS

A build sets a flag (like an old loader spelling) that the current Node no longer accepts.

A version skew between local and CI Node

The build flags suit the local Node but the CI runner runs a version that rejects them.

How to fix it

Align the Node version with the flags

1. Pin the CI Node version to one that accepts the build flags.
2. Re-run the build.

- uses: actions/setup-node@v4
  with:
    node-version: 20

Update the flags to the supported form

1. Replace removed flags (for example --loader) with the supported equivalent (--import).
2. Re-run with the corrected NODE_OPTIONS.

How to prevent it

• Keep build-time NODE_OPTIONS in sync with the pinned CI Node version, and update flags when Node deprecates or removes them.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation