gatsbyjs/gatsby · critical

Gatsby requires Node.js ${MIN_NODE_VERSION} or higher (you h

Error message

Gatsby requires Node.js ${MIN_NODE_VERSION} or higher (you have ${version}).
      Upgrade Node to the latest stable release: https://gatsby.dev/upgrading-node-js

What it means

Enforced at CLI startup via `semver.satisfies(process.version, '>=MIN_NODE_VERSION')`. For Gatsby major 5 the floor is Node 18.0.0; for earlier majors it is 14.15.0. If the running Node does not meet the floor, the CLI panics before doing any work.

Source

Thrown at packages/gatsby-cli/src/index.ts:32

}

// Ensure stable runs on Windows when started from different shells (i.e. c:\dir vs C:\dir)
if (os.platform() === `win32`) {
  ensureWindowsDriveLetterIsUppercase()
}

// @ts-ignore - TODO: Remove _CFLAGS_ again
const MIN_NODE_VERSION = _CFLAGS_.GATSBY_MAJOR === `5` ? `18.0.0` : `14.15.0`
// const NEXT_MIN_NODE_VERSION = `10.13.0`

const { version } = process

if (
  !semver.satisfies(version, `>=${MIN_NODE_VERSION}`, {
    includePrerelease: true,
  })
) {
  report.panic(
    report.stripIndent(`
      Gatsby requires Node.js ${MIN_NODE_VERSION} or higher (you have ${version}).
      Upgrade Node to the latest stable release: https://gatsby.dev/upgrading-node-js
    `)
  )
}

if (semver.prerelease(version)) {
  report.warn(
    report.stripIndent(`
    You are currently using a prerelease version of Node (${version}), which is not supported.
    You can use this for testing, but we do not recommend it in production.
    Before reporting any bugs, please test with a supported version of Node (>=${MIN_NODE_VERSION}).`)
  )
}

// if (!semver.satisfies(version, `>=${NEXT_MIN_NODE_VERSION}`)) {
//   report.warn(

View on GitHub (pinned to 8b06340921)

Solutions

1. Upgrade Node to the latest LTS (>=18 for Gatsby 5): use `nvm install --lts`, `volta install node@lts`, or your platform installer.
2. Pin the Node version in the project (`.nvmrc`, `package.json#engines`, or `volta` pin) and ensure shells load it.
3. Update CI to use a Node version that satisfies the floor (e.g. `actions/setup-node` with `node-version: 18`).
4. Confirm `node -v` in the failing environment before re-running gatsby.

Example fix

# before: Node 16 with Gatsby 5
node -v  # v16.x

# after
nvm install 18
nvm use 18
node -v  # v18.x
gatsby develop

const semver = require('semver')
const MIN = '18.0.0' // Gatsby 5
if (!semver.satisfies(process.version, `>=${MIN}`, { includePrerelease: true })) {
  throw new Error(`Node >= ${MIN} required (have ${process.version})`)
}

When it happens

Trigger: Invoking any gatsby CLI command under a Node version below the required floor (e.g. Node 16 with Gatsby 5, or Node 12 with Gatsby 4).

Common situations: CI image pinned to an old Node LTS; `nvm`/`volta`/`n` shell not switched to the project's Node; deploying to a host whose default Node is below the floor; local Node not updated after a Gatsby major upgrade.

Related errors

• Something went wrong when trying to add the plugins to the p
• starter ${starterPath} doesn't exist
• You can't create a starter from the existing directory. If y
• Please mention both starter package and project name along w
• gatsby <${command}> can only be run for a gatsby site. Eithe

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/b9325a8c2ff49451. Report an issue: GitHub.