Astro unsupported Node version during build in CI

By Kaveh Alemi·Latchkey

Astro requires a supported, modern Node.js version. When the runner uses an older Node, install can warn about an unmet engine and the build can fail on syntax or APIs the old runtime lacks. Pin the runner Node to a supported version.

What this error means

The build fails with an "Unsupported engine" warning turned error, or a syntax/API error that traces to an old Node version on the runner.

npm warn EBADENGINE Unsupported engine {
  package: 'astro@4.10.0',
  required: { node: '>=18.17.1' },
  current: { node: 'v16.20.2' } }
error   The requested Node version is not supported by Astro.

Common causes

The runner Node is older than Astro requires

Astro declares a minimum Node in its engines; a runner on an older major fails the engine check or hits missing APIs.

No explicit Node version pinned in CI

Without pinning, the runner default may drift to a version Astro no longer supports.

How to fix it

Pin a supported Node version

1. Set an explicit, supported Node in the CI setup step.
2. Match it to Astro's required engines range.
3. Re-run the build on the pinned version.

- uses: actions/setup-node@v4
  with:
    node-version: '20'

Record the version in the repo

Add a .nvmrc or engines entry so local and CI use the same supported Node.

// package.json
{ "engines": { "node": ">=18.17.1" } }

How to prevent it

• Pin the CI Node to a version Astro supports.
• Keep engines/.nvmrc in sync with Astro requirements.
• Upgrade Node when upgrading Astro majors.

Frequently asked questions

Related guides

References

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