Qwik/SolidStart build fails on an unsupported Node version in CI

By Kaveh Alemi·Latchkey

Qwik, SolidStart, Vite, and vinxi require a modern Node engine. On an older runner Node the build fails with an engine warning or a syntax/API error, because the toolchain uses features the old runtime lacks.

What this error means

A qwik build or vinxi build step fails with "Unsupported engine" / "The engine 'node' is incompatible" or a runtime error for a newer API, on a runner using an out-of-date Node.

npm warn EBADENGINE Unsupported engine {
  package: 'vite@5.0.0', required: { node: '^18.0.0 || >=20.0.0' },
  current: { node: 'v16.20.2' } }
SyntaxError: Unexpected token '??='

Common causes

The runner Node is older than the toolchain requires

The default or pinned Node predates the version Qwik/SolidStart/Vite support, so the build errors.

No Node version pinned in CI

Without setup-node, the runner Node can drift below the required engine.

How to fix it

Pin a supported Node with setup-node

1. Check the engines field the toolchain requires (Node 18 or 20+).
2. Pin that Node in CI with actions/setup-node.
3. Re-run the build on the supported runtime.

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

Declare engines to fail fast

Set engines.node so an unsupported runtime is caught early rather than mid-build.

{
  "engines": { "node": ">=20" }
}

How to prevent it

• Pin the CI Node with setup-node to a supported version.
• Declare engines.node to match the toolchain.
• Track Vite/Qwik/SolidStart Node requirements when upgrading.

Frequently asked questions

Related guides

References

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