Bitbucket Self-Hosted Runner Offline - Jobs Stuck Queued

By Kaveh Alemi·Latchkey

Your self-hosted runner dropped offline - the process stopped, the host lost network, or its credentials expired - so steps targeting it sit queued with nothing to run them.

What this error means

Steps that target the self-hosted runner stay queued indefinitely. The Runners page shows the runner as offline or disabled. Restarting the runner clears the backlog, which points at a transient connectivity or process issue.

Bitbucket UI

Runner "linux-build-01" is OFFLINE.
Waiting for a runner to become available...

Diagnose it: schema, branch match, or step isolation?

Bitbucket validates the pipeline file on push, and a schema error disables the pipeline rather than failing a build, which looks like nothing happened. Each step also runs in a fresh container, so nothing carries between steps unless declared.

Terminal

curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

Common causes

The runner process stopped or the host lost network

A crashed/stopped runner container, a rebooted host, or a network blip disconnects the runner from Bitbucket. It cannot accept jobs while disconnected.

Expired credentials or outdated runner

A rotated OAuth token or an outdated runner version can prevent the runner from re-registering, so it never comes back online.

How to fix it

Restart the runner and confirm it reconnects

Terminal

# on the runner host
docker restart <runner-container>
# or systemd-managed
systemctl restart bitbucket-runner
# then confirm it shows ONLINE on the Runners page

Check connectivity, credentials, and version

Verify the host can reach Bitbucket over the network/proxy.
Re-create the runner if its OAuth credentials were revoked or rotated.
Update to a current runner image so registration is not rejected.

How to prevent it

Run runners under a supervisor (systemd/Docker restart policy) so they self-recover.
Keep more than one runner online for redundancy.
Alert on runner offline status and keep the runner version current.

Frequently asked questions

What causes Bitbucket Self-Hosted runner offline?

There are 2 common causes: the runner process stopped or the host lost network and expired credentials or outdated runner. A crashed/stopped runner container, a rebooted host, or a network blip disconnects the runner from Bitbucket.

How do I fix Bitbucket Self-Hosted runner offline?

There are 2 fixes depending on which cause you have: restart the runner and confirm it reconnects and check connectivity, credentials, and version. Work through them in order, since the first is the most common.

What does Bitbucket Self-Hosted runner offline actually mean?

Steps that target the self-hosted runner stay queued indefinitely.

How do I stop Bitbucket Self-Hosted runner offline happening again?

Run runners under a supervisor (systemd/Docker restart policy) so they self-recover. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.

References

GitHub Actions documentation