GitHub Actions matrix max-parallel Not Limiting Concurrent Jobs

You set strategy.max-parallel to throttle matrix jobs, but they all still run at once - usually because the key is misplaced, set too high, or capped first by the account-wide concurrency limit.

What this error means

All matrix combinations start simultaneously despite max-parallel, overwhelming a shared resource, or far fewer run than expected because the plan concurrency cap is the real limit.

strategy:
  matrix:
    shard: [1, 2, 3, 4, 5, 6]
  max-parallel: 2   # must sit under strategy, beside matrix

Common causes

max-parallel placed at the wrong level

max-parallel belongs under strategy, alongside matrix and fail-fast. Nested under matrix or at the job level it is ignored or rejected.

Account concurrency caps it first

max-parallel only limits within the matrix. The plan-wide concurrent-job limit can already be lower, so raising max-parallel has no effect beyond that ceiling.

How to fix it

Place max-parallel under strategy

strategy:
  fail-fast: false
  max-parallel: 2
  matrix:
    shard: [1, 2, 3, 4, 5, 6]

Account for other limits

1. Remember max-parallel only throttles this matrix, not other jobs in the run.
2. For a shared external resource, also use a concurrency group to serialize across runs.
3. Check your plan concurrent-job limit, which caps everything regardless of max-parallel.

How to prevent it

• Keep max-parallel directly under strategy.
• Use concurrency groups to serialize access to shared external systems.
• Know your account concurrency limit when tuning matrix parallelism.

Related guides