gatsbyjs/gatsby · error

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

CLI startup check in gatsby-cli: semver reports the running Node version does not satisfy the minimum required by this Gatsby major (18.0.0 for v5). report.panic aborts before any command runs, directing the user to upgrade Node.

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 e85d62f177)

Solutions

1. Upgrade Node.js to the latest stable release (>= 18 for Gatsby 5)
2. Use nvm to install/switch to a supported Node version
3. Ensure CI/deploy environments also use a supported Node version

When it happens

Trigger: Thrown at packages/gatsby-cli/src/index.ts:32 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/58a9eaf59392884b. Report an issue: GitHub.