GitHub Actions "matrix ... exceeds the max number of jobs (256)"

By Daniel Zoghalchali·Latchkey

The Cartesian product of your matrix dimensions plus include entries expanded to more than 256 jobs, which is the hard per-workflow-run limit, so GitHub rejects the workflow.

What this error means

The workflow fails to start with a message that the matrix exceeds the maximum number of 256 jobs. No jobs run until the matrix is trimmed.

Error: The job matrix generated 384 jobs which exceeds the maximum of 256 jobs allowed per workflow run.

Common causes

Too many combined dimensions

Several matrix axes multiplied together (os x version x arch x flag) blow past 256 combinations.

Large include/exclude expansion

Many include entries add jobs on top of the base product, pushing the total over the cap.

How to fix it

Shrink the matrix

1. Drop axes or values you do not actually need to test.
2. Use exclude to prune invalid combinations.
3. Split the matrix across multiple workflows or jobs.
4. Reserve the full matrix for nightly runs, not every push.

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

How to prevent it

• Keep matrices to the combinations that add real coverage.
• Use exclude to prune invalid pairs early.
• Push exhaustive matrices to scheduled runs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions