GitHub Actions matrix exclude removed all combinations and the job never runs

By Kaveh Alemi·Latchkey

exclude prunes combinations from the Cartesian product. If the exclude filters are too broad or partially match, they can remove every combination, and the matrix job silently produces zero jobs.

What this error means

A matrix job shows no legs at all; the job appears to be skipped because every combination was excluded.

strategy:
  matrix:
    os: [ubuntu-latest]
    node: [18, 20]
    exclude:
      - os: ubuntu-latest
# excludes every os=ubuntu-latest combination -> matrix is empty

Common causes

Partial-key exclude matches too much

An exclude entry matches any combination containing those keys, so a single-key exclude can wipe out an entire axis.

Excludes overlap the whole product

Several exclude entries together can cover every generated combination.

How to fix it

Make exclude entries fully specify the combination

1. List every matrix key in each exclude entry so it removes exactly one combination.
2. Re-count remaining combinations after each exclude.

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

Prefer include to build an explicit allowlist

1. When most combinations are invalid, define only the valid ones with include.
2. This avoids accidentally pruning everything via exclude.

How to prevent it

• After adding exclude, confirm at least one combination survives.
• Use include for sparse matrices instead of heavy exclude lists.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions