GitHub Actions "job matrix exceeds 256 entries"

A single job matrix is limited to 256 entries after expansion. The cross-product of several dimensions grows quickly and can blow past the cap. This is a deterministic limit.

What this error means

The workflow fails to start because a matrix expands to more than 256 combinations.

github-actions

Error: Matrix vector 'include' exceeds maximum of 256 jobs.

Common causes

Cross-product too large

Multiple matrix dimensions multiply into more than 256 combinations.

Generated matrix unbounded

A matrix built from fromJSON of generated data produces too many entries.

How to fix it

Shrink the matrix

Reduce dimensions or use exclude to drop unneeded combinations.
Use include to enumerate only the combinations you need.
For generated matrices, cap the number of entries when building the JSON.

.github/workflows/ci.yml

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20]
    exclude:
      - { os: macos-latest, node: 18 }

How to prevent it

Keep matrix expansion under 256 entries.
Trim the cross-product with include/exclude.

Related guides

GitHub Actions "too many jobs in workflow (256 limit)"Fix the GitHub Actions error where a single workflow run produces more than the 256-job limit. GitHub Actions matrix job "reserved characters in name"Fix the GitHub Actions error where a matrix job name uses reserved or invalid characters that break run-name… GitHub Actions "step output exceeds max size"Fix the GitHub Actions error where a step writes an output to GITHUB_OUTPUT that exceeds the allowed size.