Troubleshoot problems in Pipelines

We’ve put together a list of problems users run into, and their potential solutions. We also encourage you to use the Atlassian Community to find answers and ask questions about building your own pipelines. If a feature of Bitbucket is causing problems, contact technical support. Please note they cannot help with problems in your own scripts and tools.

See also:

Something weird is happening in the interface

Sometimes browser extensions/addons can override our interface, even ones you'd think would have nothing to do with it! As a troubleshooting step it's worth temporarily disabling all browser extensions, and trying the action again.

Invalid bitbucket-pipelines.yml

  • YAML must be indented with spaces only, not tabs 

  • The script for a step does not support a multi-line string yet. Please provide a list of commands

  • Try validating your bitbucket-pipelines.yml with with an online YAML linter

  • Have a look at how to configure your bitbucket-pipelines.yml

My script isn't working and I'm not sure why

Rather than use up build minutes going through a cycle of:

  1. make a small change

  2. commit

  3. watch where the pipeline fails

  4. repeat

You can debug your pipelines locally using Docker. This means you can run an identical docker container to the one we use, and then interactively run each command in your script to find out the root cause of any issues.

I committed the bitbucket-pipelines.yml file, but I don't see any running builds

If you committed and pushed the bitbucket-pipelines.yml, but you can't see any information about builds:

  • Check whether Pipelines is enabled. For more information, see Get started with Bitbucket Pipelines.

  • If Pipelines is enabled and the bitbucket-pipelines.yml file is in the root of your repository, try pushing a change. The builds are triggered on every commit that happens after you enable Pipelines.

  • Try refreshing your browser.

My branch doesn't build

Make sure that there is a bitbucket-pipelines.yml file in the root of your branch. To build a branch, you must specify a default or a branch-specific pipeline configuration. For more information, see Configure bitbucket-pipelines.yml.

I did a push with multiple branches, but I don’t see any running builds

Pipelines accepts up to five branches in one push, so you might want to check whether you’re within the limit. 

We’ve restricted the number of branches in a push to prevent unintended usage of your build minutes.

I can't get a pipe working

Make sure to check out the readme for the pipe you are using; it's linked to from the editor and the pipes page. The readme contains more detail about using the pipe and where you can get support, as that changes depending on who developed it.

My pipeline build is failing to trigger

Webhook payload is limited to 256 KB. Webhooks may silently fail to trigger if their payload is too large.

Docker push failing — tag does not exist


Docker push commands (docker push) are failing with the error tag does not exist. For example:

1 2 3 4 docker push ${IMAGE_NAME} Using default tag: latest The push refers to repository [<repository>] tag does not exist: <repository>:latest


In June 2022, Bitbucket Pipelines upgraded to Docker CLI version 20. Prior to Docker CLI version 20, the docker push command would push all available image tags if no tag was specified. For version 20, the Docker CLI updated the docker push command to try push the latest tag, if a tag is not specified. If the latest tag does not exist, the command will fail.


To resolve the issue, update the docker push command in the pipeline to either:

  • Add the --all-tags (or -a) option to the docker push command to push all available tags. Such as:

    1 docker push --all-tags IMAGE_NAME


    1 docker push -a IMAGE_NAME
  • Specify the tag to be pushed, such as:

    1 docker push IMAGE_NAME:TAG
  • Install an older version of Docker CLI in the image. For example:

    1 2 3 4 5 6 7 8 9 10 11 12 pipelines: default: - step: services: - docker script: - curl -s -O - tar --extract --file=docker-19.03.15.tgz - ls -al ./docker - export PATH=./docker:$PATH - which docker - docker version

Additional Help