How to Retry a Failing Step in Bitbucket Pipelines

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.

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.

Related guides