Buglyst
Explore Practice
All guides

LEARN \u00b7 DEBUGGING GUIDE

Node version mismatch in CI: how to debug it

You write code using `Array.findLast()` or `fetch()` or top-level await. It works locally on Node 20. CI runs Node 18 and fails with 'not a function' or a parse error.

BeginnerCI/CD debugging

What this usually means

Different environments run different versions of Node.js. Your local machine might have Node 20, but the CI runner image defaults to an older LTS version like Node 18 or even 16. Code that uses newer JavaScript features or APIs will fail to parse or throw 'is not a function' errors on older runtimes. This is not a code bug — it is a runtime version gap.

( 01 )Fast diagnosis

The first ten minutes \u2014 establish facts before touching code.

  • 1Check the Node version in the CI log. The first few lines of a CI job typically print the Node version.
  • 2Run `node --version` locally and compare to the CI version.
  • 3Check the CI config file for the Node version specification. Is it pinned? Is it using `node-version: 'lts/*'` (which changes over time)?
  • 4Check `package.json` `engines` field. Does it specify a minimum Node version? Is CI enforcing it?
  • 5Look for `.nvmrc` or `.node-version` files. Do they exist? Does CI use them?
( 02 )Where to look

The specific files, logs, configs, and dashboards that usually own this bug.

  • searchCI pipeline config (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`) — Node version setup step
  • searchDockerfile `FROM node:XX` — the base image version
  • search`package.json` `engines` field
  • search`.nvmrc` or `.node-version` file in the project root
  • searchCI job logs — first 10 lines showing runtime version
  • searchThe specific failing code — which Node API or syntax feature is it using?
( 03 )Common root causes

Practical causes, not theory. These are the things you will actually find.

  • warningCI config does not pin a Node version and uses the runner's default
  • warningCI config pins a version that is older than what the team uses locally
  • warningDocker base image (`FROM node:18`) is older than the code requires
  • warning`engines` in package.json is set but CI does not check it
  • warningA team member upgraded Node locally but did not update CI config
  • warningCI runner image was updated and the new default version is different
( 04 )Fix patterns

Concrete fix directions. Pick the one that matches your root cause.

  • buildPin the exact Node version in CI config to match local development: `node-version: '20'` or `node-version-file: '.nvmrc'`
  • buildAdd a CI step that checks the running Node version against `engines` in package.json
  • buildUpdate the Dockerfile base image: `FROM node:20-alpine`
  • buildUse `.nvmrc` to declare the project Node version and reference it from CI and Docker
  • buildAdd `engine-strict: true` in `.npmrc` so npm/yarn warns on version mismatch
( 05 )How to verify

A fix you cannot prove is a guess. Close the loop.

  • verifiedPush a commit and check the CI log shows the correct Node version.
  • verifiedAdd a CI step that asserts `node --version` matches the expected version.
  • verifiedRun the CI build command locally with the same Node version as CI.
  • verifiedVerify the Docker image builds and runs with the correct Node version.
  • verifiedTest that code using newer Node features works in CI after the version fix.
( 06 )Mistakes to avoid

Things that make this bug worse or harder to find.

  • warningUsing `node-version: 'latest'` — it changes without notice and can break builds
  • warningNot pinning the Node version at all and relying on the CI runner's default
  • warningUpdating the Node version locally without updating CI, Docker, and deployment configs
  • warningNot using `.nvmrc` when the team uses nvm for version management
  • warningAssuming all CI runners have the same default Node version