Bitbucket Max Number of Steps Exceeded

A single pipeline definition declared more steps than Bitbucket allows per pipeline. The cap counts all steps (serial and parallel) in one pipeline run, so a sprawling matrix or long sequence trips it.

What this error means

The pipeline fails configuration noting the maximum number of steps was exceeded. It is a structural limit, not a runtime error - the pipeline never starts.

Configuration error: the pipeline exceeds the maximum number of
steps allowed (100) per pipeline.

Common causes

Too many steps in one pipeline

Every serial and parallel step counts toward the per-pipeline cap. A large fan-out or a long sequence pushes the total over the limit.

Duplicated steps that could be consolidated

Repeated near-identical steps (per-package, per-target) inflate the count when a single parameterized step or fewer parallel branches would do.

How to fix it

Consolidate and split the pipeline

Combine related work into fewer steps and move independent flows into separate pipelines.

pipelines:
  default:
    - step:
        name: Build and test
        script:
          - ./build.sh
          - ./test.sh   # combine related commands instead of many tiny steps

Reduce fan-out

1. Merge tiny sequential steps that share a container into one step.
2. Trim the parallel matrix to the branches you truly need.
3. Split unrelated flows into separate custom/branch pipelines.

How to prevent it

• Keep steps coarse-grained; avoid one step per command.
• Limit parallel fan-out to what is necessary.
• Split large workflows across multiple pipelines.

Related guides