GitHub Actions job exceeds the maximum number of steps

By Kaveh Alemi·Latchkey

A single job has a maximum number of steps it may declare. A job that lists more than the allowed steps fails validation and does not run.

What this error means

A job fails to load with an error that it has too many steps or exceeds the per-job step limit.

Error: Job 'build' has too many steps. A job may contain at most the maximum allowed number of steps.

Common causes

Sequential steps used where a loop fits

Repeating near-identical steps inflates the count beyond the limit.

One job doing too much

A job that bundles many phases hits the step cap.

How to fix it

Collapse repetitive steps into one script

1. Replace many similar steps with a single run step that loops.
2. Move sequences into a committed script.

steps:
  - run: |
      for t in a b c d; do ./run.sh "$t"; done

Split the job

1. Break the work across multiple jobs connected with needs.
2. Use a matrix to parallelize repeated work instead of inline steps.

How to prevent it

• Loop in a script rather than enumerating steps.
• Split large jobs and use matrices for repetition.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions