Troubleshooting runners

Checking the status of a runner

The runner status can be checked on the Runners page associated with the workspace or repository.

  • To find the status of a workspace runner, select Settings on the left sidebar of the workspace, and select Workspace runners under Pipelines on the left sidebar navigation.

  • To find the status of a repository runner, select Repository settings on the left sidebar of the repository, and select Runners under Pipelines 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.

runner display in the user interface with online status

Reviewing runner logs

Runner logs are located in /<runner_working_directory>/<runnerUuid>/runner*.log.

By default, the working directory is /tmp and the logs are located in /tmp/<runnerUuid>/runner*.log but you can change the working directory of your runner.

Build and services logs for a step are removed from a runner host, but can be found in the step logs on the Pipeline's user interface.

Updating a runner version

If you experience an issue with a runner, update the runner to the latest version.

  1. Stop the runner.

  2. Pull the latest runner version using the command below:

1 docker image pull

3. Restart the runner.

Troubleshooting errors when starting a runner

An error message


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 run docker container rm -f runner-76b247e7-b925-5e7b-9da2-1cda14c4ff2c command.

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.

Troubleshooting errors during step execution

An error message

Step execution stage


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


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

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


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.

{"message":"toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading:"}

Pulling images locally (rate limit reached)

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


Additional Help