GitHub Actions matrix "max-parallel" not limiting concurrency in CI

By Daniel Zoghalchali·Latchkey

max-parallel caps how many jobs from a single matrix run at the same time. If all legs still run at once, the key is either misplaced (not under strategy), misspelled, or you are limited by runner availability rather than the setting.

What this error means

Every matrix leg starts simultaneously despite a max-parallel value, or the setting appears to have no effect on concurrency.

strategy:
  matrix:
    node: [18, 20, 22, 23]
  # max-parallel indented under matrix by mistake, so it is treated as a vector

Common causes

max-parallel is nested under matrix

It must be a sibling of matrix, directly under strategy. Placed inside matrix, it is read as a vector name and ignored as a limit.

The cap is higher than the leg count

If max-parallel is greater than or equal to the number of legs, nothing is throttled, so it looks like it has no effect.

How to fix it

Place max-parallel under strategy

1. Move max-parallel to the same indentation level as matrix.
2. Set it below the number of legs you want to throttle.
3. Re-run and confirm only that many legs start at once.

strategy:
  max-parallel: 2
  matrix:
    node: [18, 20, 22, 23]

Distinguish limits from runner supply

If fewer legs run than the cap, you may be out of concurrent runners or hitting account concurrency limits, not the matrix setting.

How to prevent it

• Keep max-parallel and fail-fast as siblings of matrix under strategy.
• Set max-parallel below the leg count to actually throttle.
• Check account and runner concurrency when legs queue unexpectedly.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions