Bitbucket Self-Hosted Runner Setup Incomplete - Never Registers

A freshly set-up self-hosted runner never appears online. The install command was incomplete, the host lacks Docker or permissions, or the runner could not reach Bitbucket to register.

What this error means

After running the runner setup command, the Runners page never shows the runner, or shows it briefly then drops it. Jobs targeting it stay queued because registration did not complete.

Runner failed to register: unable to reach
https://api.bitbucket.org - check network and OAuth credentials.

Common causes

Incomplete or mis-copied setup command

The runner setup command embeds an account UUID, repository/workspace UUID, and a one-time OAuth token. A truncated or stale command fails to register.

Host missing Docker, permissions, or network

Linux Docker runners need Docker installed and the runner able to use the socket. A missing Docker, a permissions problem, or blocked egress to Bitbucket stops registration.

How to fix it

Re-run a fresh setup command with prerequisites

Generate a new runner in settings (the OAuth token is one-time) and run it on a host with Docker available.

# on the runner host
docker run -d \
  -e ACCOUNT_UUID='{...}' \
  -e REPOSITORY_UUID='{...}' \
  -e RUNNER_UUID='{...}' \
  -e OAUTH_CLIENT_ID='...' \
  -e OAUTH_CLIENT_SECRET='...' \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name bb-runner docker-public.packages.atlassian.com/sox/atlassian/bitbucket-pipelines-runner

Verify prerequisites and connectivity

1. Confirm Docker is installed and the runner can access /var/run/docker.sock.
2. Check the host can reach Bitbucket over HTTPS (and through any proxy).
3. Generate a new runner if the one-time OAuth token was already consumed.

How to prevent it

• Copy the full setup command in one piece for each new runner.
• Bake Docker and required permissions into the runner host image.
• Verify egress to Bitbucket before relying on the runner for builds.

Related guides