Node ERR_INVALID_ARG_TYPE in CI - Pass the Right Argument Type

By Kaveh Alemi·Latchkey

ERR_INVALID_ARG_TYPE is thrown by Node core APIs when you pass an argument of the wrong type, most often undefined where a string or Buffer was required.

What this error means

A node process throws TypeError [ERR_INVALID_ARG_TYPE], for example "The path argument must be of type string. Received undefined", at a core API call.

node

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type
string or an instance of Buffer or URL. Received undefined
    at Object.readFileSync (node:fs:451:10) {
  code: 'ERR_INVALID_ARG_TYPE'
}

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.

Terminal

# 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 missing environment variable resolved to undefined

A path or value derived from an env var that is unset in CI becomes undefined and is passed straight to a core API.

A function returned undefined where a value was expected

An upstream call returned nothing, and that undefined flowed into a strict core API.

How to fix it

Validate inputs before the core call

Assert the argument is defined and the right type before passing it.
Fail with a clear message if the input is missing.

JavaScript

if (typeof path !== 'string') {
  throw new Error('CONFIG_PATH is not set');
}

Set the missing CI environment variable

Confirm which env var the argument depends on.
Provide it in the workflow env for the failing step.

GitHub Actions

- run: node build.js
  env:
    CONFIG_PATH: ./config/ci.json

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.

.github/workflows/ci.yml

# 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

Validate external inputs and env-derived values at the boundary, and use TypeScript or schema checks so undefined cannot silently reach a core API.

Frequently asked questions

What causes Node ERR_INVALID_ARG_TYPE in CI?

There are 2 common causes: a missing environment variable resolved to undefined and a function returned undefined where a value was expected. A path or value derived from an env var that is unset in CI becomes undefined and is passed straight to a core API.

How do I fix Node ERR_INVALID_ARG_TYPE in CI?

There are 2 fixes depending on which cause you have: validate inputs before the core call and set the missing ci environment variable. Work through them in order, since the first is the most common.

What does Node ERR_INVALID_ARG_TYPE in CI actually mean?

A node process throws TypeError [ERR_INVALID_ARG_TYPE], for example "The path argument must be of type string.

How do I stop Node ERR_INVALID_ARG_TYPE in CI happening again?

Validate external inputs and env-derived values at the boundary, and use TypeScript or schema checks so undefined cannot silently reach a core API.