How to Retry a Failing Step in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

Bitbucket has no per-step auto-retry keyword - rerun failed steps from the UI or script a retry loop.

For transient failures, rerun failed steps from the pipeline view, or wrap a flaky command in a bash retry loop with backoff so the step recovers automatically.

Script-level retry with backoff

This loop retries the command up to three times with increasing backoff before failing the step.

bitbucket-pipelines.yml

pipelines:
  default:
    - step:
        name: Smoke test
        image: curlimages/curl:8
        script:
          - |
            for i in 1 2 3; do
              curl -fsS https://api.example.com/health && exit 0
              echo "attempt $i failed; retrying"
              sleep $((i * 5))
            done
            exit 1

Gotchas

Bitbucket has no retry: keyword - automatic retry must be scripted in the step or done by rerunning from the UI.
Rerunning failed steps restarts from the failed step using the prior steps' artifacts, not from scratch.
Only retry transient/infra commands in the loop; do not loop test suites and hide real failures.

Verify it actually works

Bitbucket validates bitbucket-pipelines.yml on push, and a schema error disables the pipeline rather than failing a build, which can look like nothing happened at all.

Terminal

# validate before pushing
curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

# confirm which pipeline definition matched
# Pipelines -> the run -> "Configuration" tab

Constraints that catch people out

Each step runs in a fresh container. Nothing persists between steps unless it is declared as an artifact or a cache.
The default memory allocation per step is limited, and service containers share that budget, so adding a database service can push a previously passing build into an out-of-memory failure.
Only branches with a matching branches: definition run; a push to an unmatched branch silently runs nothing.
Artifacts are passed forward only to later steps in the same pipeline, not between pipelines.

Frequently asked questions

How do I retry a Failing Step in Bitbucket Pipelines?

For transient failures, rerun failed steps from the pipeline view, or wrap a flaky command in a bash retry loop with backoff so the step recovers automatically.

Script-level retry with backoff?