GitHub Actions "The self-hosted runner is offline"

By Kaveh Alemi·Latchkey

A self-hosted runner must hold a live connection to GitHub to receive jobs. If the runner service is stopped, the host is down, or the network is blocked, the runner shows offline and matching jobs queue forever.

What this error means

Jobs targeting a self-hosted label stay queued; the runner shows Offline in repo/org settings.

The self-hosted runner: my-runner-01 is offline.
Waiting for a self-hosted runner with the requested labels to come online.

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

Common causes

Runner service stopped

The actions-runner service crashed or was not started after a reboot.

Host down or network blocked

The machine is powered off or cannot reach GitHub due to firewall/proxy issues.

How to fix it

Restart and verify the runner

1. On the host, start the runner service (svc.sh start) or run ./run.sh.
2. Confirm outbound access to github.com and the Actions endpoints.
3. Verify the runner shows Idle in settings, then re-run the job.

Offload to managed runners

1. Latchkey provisions runners on demand from warm pools, removing offline-host and queue-forever failure modes.
2. Point runs-on at the Latchkey label to avoid babysitting self-hosted hosts.

jobs:
  build:
    runs-on: latchkey-small

The failures that are not your workflow

• Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
• Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
• A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
• A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

How to prevent it

• Run the runner as a service that auto-restarts on boot.
• Monitor runner connectivity and alert on offline status.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions