The hosted runner encountered an error while running your job

By Kaveh Alemi·Latchkey

"The hosted runner encountered an error while running your job" in GitHub Actions means the machine running your job faulted, not that a command failed. Before you write it off as a platform blip, check whether your own job is what took the runner down, because that version comes back.

What this error means

A job that was producing output stops, and the run summary carries one line with a parenthesised error type: "The hosted runner encountered an error while running your job. (Error Type: Disconnect.)" The other type seen in the wild is Failure. There is no annotation on a step, no exit code, and no error from the command, because the command did not report anything: the machine it was on stopped being available. Re-running the same workflow frequently succeeds, which is the detail that makes this failure easy to dismiss and expensive to dismiss twice.

The hosted runner encountered an error while running your job. (Error Type: Disconnect.)

Decide which of the two it is before you re-run

There are only two stories behind this message and they need opposite responses. Either GitHub's infrastructure faulted under a job that was behaving, in which case a re-run is the whole fix, or your job consumed the machine and the runner went with it, in which case a re-run is a coin toss you will keep paying for.

The maintainers' own framing on the runner-images tracker is the useful test: anything in your workflow that terminates the runner process, starves it for CPU or memory, or blocks its network access produces this error. So look at what the job was doing at the cut-off rather than at the message.

Three checks settle it. Which step was running, and was it memory or disk heavy? Does the elapsed time match a step that had just started something large? And was GitHub reporting an Actions incident in that window? Two noes and a yes on the first question means the job is the cause.

- name: Resource ceiling, printed before the heavy step
  run: |
    free -m
    df -h /
    nproc

Common causes

Your job exhausted the runner and took the agent with it

Memory first, disk second. A build, a test matrix or a container that peaks against the machine ceiling leaves the kernel choosing a process to kill, and the runner agent is an ordinary candidate. A full volume stops the agent writing its own state. Both end the job with an infrastructure message and no mention of the resource that ran out.

The re-run went green and told you nothing

This is why the failure repeats. A successful re-run is equally consistent with a one-off platform fault and with a job that sits just under the machine's limit and crosses it whenever the cache is cold or the runner is a little slower. Treating green as an answer is how the same failure arrives every few days, and each occurrence costs a full run plus the time until someone notices.

A genuine platform fault

The VM was reclaimed, the backend errored, or a regional incident took capacity with it. This does happen and the status history for the window will usually say so. In our experience it is the correct explanation far less often than it is the assumed one.

The job cut the agent off from GitHub

A step that rewrites DNS, applies firewall rules, brings up a VPN, or reconfigures the Docker network can sever the agent's connection while your own commands keep working. The job looks healthy right up to the moment the run is declared failed, and the last successful step names the change that did it.

How to fix it

Print the resource ceiling and the peak around the failing step

1. Add a step before the heavy one that prints free memory, disk and core count, so every run records what it started with.
2. Wrap the heavy command in a peak-memory measurement, which costs nothing and turns the next occurrence into a number.
3. Compare a failed run against a successful one; a peak that sits close to the ceiling in both is your answer.

- run: /usr/bin/time -v npm run build 2>&1 | grep -E "Maximum resident|Exit status"
- if: always()
  run: df -h / && free -m

Lower the peak before you raise the machine

Pin the worker count of anything that forks, cap container memory explicitly, stream large files instead of buffering them, and split a matrix leg that does three jobs' work. A job with headroom does not produce this message, and lowering the peak is cheaper than every other fix on this page.

- run: npx jest --maxWorkers=2
- run: docker run --memory=4g --memory-swap=4g build-image

Give the job a machine with room, once you know the peak

When the measured peak is genuinely close to the ceiling, the fix is capacity rather than tuning. A larger GitHub-hosted runner or a managed runner sized for the job removes the constraint instead of moving it a week down the road.

jobs:
  build:
    runs-on: latchkey-medium   # 4 vCPU and 16 GB against 2 vCPU and 8 GB

Move anything that reconfigures the network to the end

If the job must change DNS, firewall rules or Docker networking, do it as late as possible, scope it to a container rather than the host, and restore it in an always() step. The agent needs the same route out that your commands do.

What the runner is fighting for

A standard GitHub-hosted Linux runner is a small machine, and the agent is one process on it. It has to keep answering GitHub while your job does whatever it does, and it has no special protection when memory runs short: the kernel out-of-memory killer chooses by score, not by importance. A build that peaks near the ceiling can take the agent instead of itself, which is how a memory problem arrives disguised as an infrastructure error.

Disk does the same thing more quietly. The agent writes logs and state continuously, and when the volume is full those writes fail rather than block. A job that fills the disk in one step can produce a disconnect in the next one, with nothing in between that names the disk.

The third path is the network, and it is self-inflicted more often than people expect. A step that edits /etc/resolv.conf, adds firewall rules, starts a VPN client or reconfigures Docker networking can cut the agent's own route to GitHub while your commands carry on working through a different path.

What a managed runner changes here

Latchkey has no detection pattern for this failure, and cannot have one. The self-heal wrapper lives on the runner next to your step; when the runner is what failed, the wrapper is gone before there is anything to diagnose. Any claim to repair it automatically would be a claim made by a process that no longer exists.

What a managed runner changes is the ceiling and how long the machine lives. Latchkey runners are sized per configuration and created for one job each, then destroyed, so a job that needs headroom gets a bigger machine rather than a bigger risk, and no state accumulates between runs to push the next job closer to the edge.

The honest limit is the same anywhere: infrastructure faults happen, and you re-run. What this page is worth is the five minutes at the start, telling the fault you cannot control from the ceiling you can.

How to prevent it

• Record memory and disk on every run so the next occurrence is a comparison rather than an investigation.
• Keep peak usage well under the runner ceiling instead of near it, and pin worker counts.
• Scope network changes to containers, and never leave a modified host route in place across steps.
• Count these failures per workflow. A rate rather than an event is what tells you it is yours.
• Re-run failed jobs rather than whole runs, so an infrastructure blip costs one job instead of the pipeline.

Frequently asked questions

Related guides

References

• actions/runner-images#10401: hosted runner encountered an error (Error Type: Disconnect)
• GitHub community discussion #126539: the same error with Error Type: Failure
• GitHub-hosted runners: standard runner specifications
• GitHub Actions: re-running workflows and jobs, the 30 day and 50 attempt limits
• Latchkey documentation: runner sizes, and one job per machine
• GitHub Actions documentation