GitHub Actions "too many jobs in workflow (256 limit)"
A single workflow run is limited to 256 jobs, counting all matrix expansions. Large matrices or many jobs that fan out together exceed the cap and the run is rejected. This is a hard limit.
What this error means
A workflow with large matrices or many jobs fails to start because the total number of jobs in the run exceeds 256.
github-actions
Error: The workflow run exceeds the maximum of 256 jobs.Common causes
Matrix expansion too large
One or more matrices expand into a job count that, combined, exceeds 256.
Too many distinct jobs
The workflow defines a very large number of independent jobs in one run.
How to fix it
Reduce or split the job count
- Trim matrix dimensions or use include to target only needed combinations.
- Split the work across multiple workflows triggered separately.
- Group fine-grained jobs into fewer steps where possible.
.github/workflows/ci.yml
strategy:
matrix:
include:
- { os: ubuntu-latest, node: 20 }
- { os: windows-latest, node: 20 }How to prevent it
- Keep total job count (after matrix expansion) under 256 per run.
- Use include to cover only the combinations you actually need.
Frequently asked questions
What causes ""too many jobs" (256)"?
One or more matrices expand into a job count that, combined, exceeds 256.
How do I fix "too many jobs" (256)?
Reduce or split the job count
Related guides
GitHub Actions "job matrix exceeds 256 entries"Fix the GitHub Actions error where a single job matrix expands to more than 256 entries.
GitHub Actions "reusable workflow exceeds nesting limit (4)"Fix the GitHub Actions error where reusable workflows are nested more than four levels deep.
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.