GitHub Actions matrix exceeds the 256 job limit in CI

A single matrix run may generate at most 256 jobs. When the cross product of your vectors (plus include additions) exceeds that, GitHub rejects the matrix before running it.

What this error means

The workflow fails to start with a message that the matrix generates more than 256 jobs. The number grows fast because vectors multiply together.

Actions

Error: A strategy matrix cannot contain more than 256 jobs. This matrix generates 384 jobs.

Common causes

Too many vectors multiplied together

Three OSes times eight versions times sixteen shards is 384 combinations. The cross product exceeds 256.

A dynamic matrix generated an oversized list

A fromJSON matrix built from data (branches, packages) grew past 256 entries without any cap.

How to fix it

Reduce the cross product

Trim a vector to the versions or platforms you actually need to test.
Use include/exclude to test only meaningful combinations instead of the full product.
Split unrelated dimensions into separate jobs.

.github/workflows/ci.yml

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

Cap a dynamic matrix in generation

Slice the generated array so it can never exceed the limit, and batch the rest into a follow-up run.

bash

jq -c '.[0:256]' all.json

How to prevent it

Keep the cross product under 256 by pruning vectors.
Prefer targeted include/exclude over the full product.
Cap dynamically generated matrices before emitting them.