GitHub Actions toJSON output too large to feed a dynamic matrix

By Kaveh Alemi·Latchkey

Dynamic matrices are built by emitting JSON from one job and reading it with fromJSON in another. The matrix and its expanded values are subject to size limits, and very large generated JSON can blow past them or simply produce too many jobs.

What this error means

A dynamic matrix job fails to expand, errors on an oversized value, or generates a job count that hits the matrix maximum.

Error: The maximum number of jobs in a matrix is 256.
A job matrix can generate a maximum of 256 jobs per workflow run.

Common causes

Generated job list exceeds the 256 matrix cap

A matrix can expand to at most 256 jobs per run; a large dynamic list trips this hard limit.

Oversized values embedded per leg

Stuffing large blobs into matrix values via toJSON inflates each leg and risks per-value size limits.

How to fix it

Cap and chunk the generated matrix

1. In the generator job, slice the list to stay well under 256 entries.
2. Shard remaining work across multiple workflow runs or a second matrix dimension.

- id: set
  run: |
    items=$(jq -c '.[0:256]' all-items.json)
    echo "matrix=${items}" >> "$GITHUB_OUTPUT"

Pass identifiers, not payloads

1. Put only small keys (ids, names) into matrix values.
2. Have each leg fetch its full payload at runtime instead of embedding it.

How to prevent it

• Keep dynamic matrix entries to short identifiers.
• Assert the generated job count before emitting it to GITHUB_OUTPUT.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions