Troubleshoot Bitbucket Cloud runners

Platform Notice: Cloud Only - This article only applies to Atlassian apps on the cloud platform.

Summary

This article provides guidance to check the different runners available in Bitbucket Cloud.

Check the status of a runner

The runner status can be checked on the Runners page associated with the workspace or repository. You need to be a workspace or repository admin respectively to check this.

  • To find the status of a workspace runner, open the workspace on Bitbucket's website, select the cog icon from the menu bar at the top and then select Workspace settings. Then, from the left sidebar of the workspace, select Workspace runners under the section Pipelines.

  • To find the status of a repository runner, open the repository on Bitbucket's website, select Repository settings on the left sidebar of the repository, and then select Runners under the Pipelines section on the left sidebar navigation.

The status can be one of the following:

  • Unregistered: The runner was created but was never run. Note: If a runner isn’t registered within one week, it will be removed.

  • Online: The runner is live and available for step scheduling.

  • Offline: The runner is not available. It may have been stopped, or there may be network connectivity issues.

  • Disabled: The runner was temporarily disabled, and steps will not be scheduled on it until it is enabled again.

Solution

Review runner logs

Build and services logs (not including the runners' logs) for a step are removed from a runner host once the step is complete. These logs can be found in the step logs on the Pipeline's user interface.

The location of the runner log files varies between operating systems and the type of runner.

Identify the runner UUID to determine log location

The runner UUID is logged as part of a build's step logs in the Pipeline's user interface. This UUID can be used to identify the correct location of runner.log files.

Runner matching labels: - linux.shell Runner name: linux-shell-runner Runner UUID: {b609961f-891e-c872-c36b-f3f2c315d186} Runner labels: self.hosted, linux.shell Runner version: current: 1.466 latest: 1.465

Review log files for Linux Docker runners

  1. Access the Linux device hosting the affected runner.

  2. Open the runner.log file using a text editor. This log file is stored in the runners' working directory, in a subdirectory named using the runners' UUID (a 32-character hexadecimal string). Such as:

    <runner_working_directory>/<runnerUuid>/runner.log

    For example:

    /tmp/b609961f-891e-c872-c36b-f3f2c315d186/runner.log

    The default working directory for the runner is the /tmp directory.

  3. Review the end of the log file for errors that need to be addressed.

Review log files for Windows PowerShell runners

  1. Access the Windows device hosting the affected runner.

  2. Using PowerShell or File Explorer, navigate to the runner installation directory (atlassian-bitbucket-pipelines-runner). This directory will be stored where PowerShell was working when the runner was started. For example: if PowerShell was working in the users' home directory, such as:

    PS C:\Users\Username>

    The runner installation directory would be C:\Users\Username\atlassian-bitbucket-pipelines-runner\

  3. Open the runner.log file using a text editor. This log file is stored in the runners' working directory, in a subdirectory named using the runners' UUID (a 32-character hexadecimal string). Such as:

    <runner_working_directory>\<runnerUuid>\runner.log

    For example:

    .\atlassian-bitbucket-pipelines-runner\temp\b609961f-891e-c872-c36b-f3f2c315d186\runner.log

    The default working directory for the runner is the \temp subdirectory of the atlassian-bitbucket-pipelines-runner directory.

  4. Review the end of the log file for errors that need to be addressed.

Review log files for Linux or macOS shell runners

  1. Access the device hosting the affected runner.

  2. Using Terminal or Finder (macOS) or Files (Linux), navigate to the runner installation directory (atlassian-bitbucket-pipelines-runner). This directory will be stored where Terminal was working when the runner was started. For example: if Terminal was working in the users' home directory (~/), such as: /Users/Username/; the runner installation directory would be /Users/Username/atlassian-bitbucket-pipelines-runner/

  3. Open the runner.log file using a text editor. This log file is stored in the runners' working directory, in a subdirectory named using the runners' UUID (a 32-character hexadecimal string). Such as:

    <runner_working_directory>/<runnerUuid>/runner.log

    For example:

    ~/atlassian-bitbucket-pipelines-runner/temp/b609961f-891e-c872-c36b-f3f2c315d186/runner.log

    The default working directory for the runner is the /temp subdirectory of the atlassian-bitbucket-pipelines-runner directory.

  4. Review the end of the log file for errors that need to be addressed.

Debug runner images

Debug docker image platform

To debug suspected platform related problems with the images used by your pipeline, there are a few checks you can run against the image to check your platform is supported:

  • Check the logs inside of Build Setup and for any service containers used by your pipeline - any warnings about potential platform incompatibilities will be logged.

  • Check the documentation provided by the image vendor to see if your platform is supported. In some instances, the image may use a specific tag per platform.

  • Run docker manifest inspect <image>:<tag> on the image, looking for a matching entry for your OS and architecture.

  • Check the platform when running docker inspect <image>:<tag>, checking that the OS and architecture matches.

Update a runner version

It is always recommended that you keep your runner updated to receive the latest patches, features, and bug fixes. To see what's included in each update, you can refer to the runner changelog.

If you encounter issues with a runner, updating it to the latest version can help resolve the problem. Follow the steps outlined in to update your runner: Updating a runner version

Troubleshoot errors when starting a runner

An error message

Solution

docker: Error response from daemon: Conflict. The container name "/runner-76b247e7-b925-5e7b-9da2-1cda14c4ff2c" is already in use by container "c3403236e3af5962ed3a9b8771561bd2021974941cc8a89a40c6c66cecb18f53". You have to remove (or rename) that container to be able to reuse that name. See 'docker run --help'.

Run the command docker container rm -f <runner-name> Replace the placeholder <runner-name> with the actual name. For example, for the error message used in this example, you would rundocker container rm -f runner-76b247e7-b925-5e7b-9da2-1cda14c4ff2

The installed Docker client must be at least version 19

To install a required version of the docker engine, refer to Install Docker Engine help.

No access to containers directory

Run the following command to add read permissions to the current user:sudo chmod +r /var/lib/docker/containers

user-ns remapping not allowed in docker settings.

User-ns remapping is not supported. Change the docker daemon configuration. Refer to the following docker docs for more information: Isolate containers with a user namespace.Isolate containers with a user namespace Isolate containers with a user namespace

The docker logging driver must be json-file.

Refer to docker docs to configure a logging driver.

failed to start daemon: error initializing graphdriver: overlay2: the backing xfs filesystem is formatted without d_type support, which leads to incorrect behavior. Reformat the filesystem with ftype=1 to enable d_type support. Backing filesystems without d_type support are not supported.

Refers to docker docs - use the OverlayFS storage driver.

.\start.ps1 : File C:\Users\Administrator\atlassian-bitbucket-pipelines-runner\bin\start.ps1 cannot be loaded. The file C:\Users\Administrator\atlassian-bitbucket-pipelines-runner\bin\start.ps1 is not digitally signed. You cannot run this script on the current system. For more information about running scripts and setting execution policy, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170

Allow unsigned scripts to run on Microsoft PowerShell.

docker pull docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner:1 Error response from daemon: Get "https://docker-public.packages.atlassian.com/v2/": Forbidden

The Runner is currently restricted from accessing the Docker image located at docker-public.packages.atlassian.com.

It is advisable to examine your network configuration to confirm that this domain is not being obstructed, whether by a firewall or by a local proxy setup.

Troubleshoot errors during step execution

An error message

Step execution stage

Solution

Cloning into ... fatal: unable to access ... : SSL certificate problem: self signed certificate in certificate chain

Cloning

Disable SSL verification on git clone in bitbucket-pipelines.yml

bash: ls: command not found (or any standard bash command)

Building

The command not found error mostly occurs when the PATH environment variable is configured as Workspace/Repository/Deployment variable. The default PATH where the binaries exist get overridden with the user-supplied PATH variable which is causing the error to appear in the build. If you have a Workspace/Repository/Deployment variable named PATH, rename it to something different, e.g. REMOTE_PATH.

{"message":"toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit"}

Pulling images locally (rate limit reached)

Log in to Dockerhub on the host to get a higher rate limit

AND/OR

Follow these instructions: https://docs.docker.com/registry/recipes/mirror/ to set up a docker pull through cache to also avoid the rate limit

References

Windows PowerShell troubleshooting:

Self-hosted Run Failure Scenarios

Updated on September 25, 2025
Platform
Cloud only
App
Bitbucket Cloud
On this pageSummarySolution

Still need help?

The Atlassian Community is here for you.
Ask the Community