GitHub Actions "The hosted runner encountered an error while running your job"
This message indicates the hosted runner itself faulted mid-job - a backend provisioning or infrastructure error, not a problem in your workflow code.
What this error means
A job that was running stops abruptly and the run summary shows that the hosted runner encountered an error while running your job. Re-running the same workflow often succeeds.
The hosted runner encountered an error while running your job. (Error Type: Disconnect.)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
Transient runner infrastructure fault
The runner VM was reclaimed, lost network, or hit a backend error, terminating the job through no fault of the workflow.
Resource exhaustion on the runner
The job drove the runner out of memory or disk, causing the host to fall over.
How to fix it
Re-run and reduce resource pressure
- Re-run the failed jobs to clear a one-off infrastructure fault.
- If it recurs, check for OOM/disk-full signals and trim the job.
- Split heavy work or move to a larger runner with more headroom.
Use auto-retrying managed runners
Managed runner platforms like Latchkey automatically retry transient runner-infrastructure failures and keep warm pools ready, so a one-off host fault re-dispatches instead of surfacing as a red build.
The failures that are not your workflow
- Exit 137 is the kernel out-of-memory killer, not an application error. Check
free -habove 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
- Keep jobs within the runner's memory and disk limits.
- Add timeouts so a wedged host does not hang indefinitely.
- Prefer a runner platform that retries transient host faults.