Bitbucket "Maximum number of steps" Exceeded in a Pipeline

By Kaveh Alemi·Latchkey

A single pipeline declared more steps than Bitbucket permits. There is a hard ceiling on steps per pipeline, and your definition went past it.

What this error means

The pipeline fails validation noting it exceeds the maximum number of steps. It is structural - nothing runs until the step count is within the limit.

Configuration error: pipeline defines more steps than the
maximum allowed per pipeline.

Common causes

Too many sequential steps

Breaking work into many tiny steps inflates the step count. Each step also adds checkout/setup overhead, so excessive splitting both hits the cap and wastes minutes.

Parallel branches counted toward the total

Steps inside parallel blocks still count. A wide fan-out can push the pipeline over the per-pipeline limit.

How to fix it

Consolidate related commands into fewer steps

Group commands that share a container into one step instead of many.

- step:
    name: Lint, test, build
    script:
      - npm run lint
      - npm test
      - npm run build

Reshape very wide pipelines

1. Merge micro-steps that run in the same image back together.
2. Move independent work into separate custom pipelines triggered as needed.
3. Use parallel for genuine concurrency, not as a way to multiply tiny steps.

How to prevent it

• Keep steps coarse-grained - one logical phase per step.
• Reserve extra steps for work that truly needs isolation or different images.
• Split unrelated flows into separate pipelines instead of one giant one.

Frequently asked questions

Related guides

References

• GitHub Actions documentation