GitHub Actions matrix "exclude" removed all combinations in CI

By Daniel Zoghalchali·Latchkey

Each exclude entry drops every combination that matches the keys it specifies. An entry with too few keys, or keys that match broadly, can subtract more legs than intended and even empty the matrix entirely.

What this error means

After adding an exclude, the matrix runs far fewer legs than expected, or no jobs at all. A fully emptied matrix then fails with "Matrix must define at least one vector".

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
    exclude:
      - os: ubuntu-latest   # drops BOTH ubuntu legs, not one combination

Common causes

An exclude entry specifies too few keys

Excluding on a single key removes every combination containing that value. exclude: [{os: ubuntu-latest}] drops all ubuntu legs across every node version.

Exclude keys unintentionally match many legs

Because exclude matches on the keys present, a broad key set silently removes a large slice of the cross product.

How to fix it

Specify every key that identifies the one combination

1. List all vector keys in the exclude entry so it targets a single leg.
2. Re-check the expanded matrix in the run summary.
3. Add multiple precise exclude entries rather than one broad one.

exclude:
  - os: ubuntu-latest
    node: 18   # removes only the ubuntu + node 18 leg

Keep a base vector so exclude cannot empty the matrix

Ensure at least one combination always survives, or the run fails with a missing-vector error.

How to prevent it

• Give exclude entries enough keys to target one combination.
• Inspect the expanded matrix after changing exclude.
• Confirm at least one leg remains after all exclusions.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions