GitHub Actions "matrix included an invalid combination"

By Kaveh Alemi·Latchkey

matrix include can add rows that pair values which are not actually supported together (an OS image with a tool version it does not provide), producing a leg that cannot run successfully.

What this error means

One matrix leg fails consistently while others pass, traceable to an include combination that is not viable (for example a runner image lacking the requested tool version).

Error: The version 'x' with arch 'arm64' on 'windows-latest' is not available for this combination.

Common causes

Include adds an unsupported pairing

An include row combines values (OS + version + arch) that no runner image or toolchain actually supports.

Exclude removed the only valid combo

An exclude pruned the working pairing, leaving an invalid one as the active leg.

How to fix it

Constrain the matrix to viable combinations

1. Remove or correct include rows that pair unsupported values.
2. Use exclude to drop known-bad combinations explicitly.
3. Verify each (os, version, arch) tuple is actually available.

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

How to prevent it

• Validate each matrix tuple against available runner images.
• Use exclude to prune unsupported pairings deliberately.
• Keep include rows consistent with real toolchain support.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions