Node ERR_INTERNAL_ASSERTION in CI - Diagnose the Internal Failure

By Daniel Zoghalchali·Latchkey

ERR_INTERNAL_ASSERTION is an internal invariant failure inside Node itself, usually triggered by a bug in Node, a native addon, or memory corruption.

What this error means

A node process crashes in CI with Error [ERR_INTERNAL_ASSERTION] and a message that this is likely a bug in Node.js, pointing at internal code rather than yours.

Error [ERR_INTERNAL_ASSERTION]: This is caused by either a bug in Node.js
or incorrect usage of Node.js internals.
Please open an issue with this stack trace at
https://github.com/nodejs/node/issues
    at new NodeError (node:internal/errors:387:5)

Diagnose it: the shell in CI is not your shell

Package scripts run under a different shell, a different PATH, and a non-interactive environment on a runner. Most scripts that fail only in CI are relying on something the login shell gave them locally: a tool on PATH, an environment variable from a dotfile, or a TTY.

# what the script can actually see
npm run env | grep -E "^(PATH|NODE_ENV|CI)=" 

# is the binary on PATH for the script, not just for you?
npm exec -- which <tool> || echo "not resolvable from npm scripts"

# run the exact script with tracing
sh -x -c "$(node -p "require('./package.json').scripts.build")"

Common causes

A bug in the running Node version

A specific Node release has an internal invariant that fails for some inputs; another version does not.

A native addon corrupting internal state

A misbehaving native module violates Node internal expectations, tripping the assertion.

How to fix it

Pin a different Node version

1. Switch the CI Node version to a known-good release.
2. Re-run to see if the internal assertion clears.

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

Isolate or update the native addon

1. Disable the suspect native dependency to confirm it is the trigger.
2. Upgrade it or replace it with a pure-JS alternative.

Make failures fail the job

A multi-command script can report success while a middle command failed, which produces the worst kind of CI result: a green build that shipped something broken.

# pipefail is NOT set by default in every runner shell
- name: Build
  shell: bash
  run: |
    set -euo pipefail
    npm run build | tee build.log

How to prevent it

• Pin and test Node version upgrades, keep native addons current, and report reproducible internal assertions upstream with the stack trace.

Frequently asked questions

Related guides

References

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