GitHub Actions matrix setup step: version not found for a combination in CI

By Daniel Zoghalchali·Latchkey

A single matrix leg fails when its setup action (setup-node, setup-python, and similar) cannot resolve the version for that combination, often because the version does not exist for the OS or was never published.

What this error means

Most legs pass but one fails at the setup step with a message that the requested version could not be found or is not available for that platform.

Error: Unable to find Node version '21.99.0' for platform linux and architecture x64.

Common causes

A vector value names a non-existent version

A version in the matrix (a typo or a not-yet-released build) has no matching toolchain, so setup fails only for that leg.

The version exists but not for this OS or arch

A combination pairs a version with an OS or architecture for which no build is published, so only that combination fails.

How to fix it

Pin only versions that exist for every leg

1. Correct the version value to a real, published release.
2. Confirm it is available for each OS in the matrix.
3. Use exclude to drop unsupported OS/version pairs.

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20, 22]
    exclude:
      - os: windows-latest
        node: 18

Let setup resolve a range

Use a major or partial version so the setup action picks a real published build for each platform.

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

How to prevent it

• Verify each version value is published for every matrix OS.
• Prefer version ranges the setup action can resolve.
• Exclude combinations with no available toolchain.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions