# GitHub Actions "No runner matching the specified labels"

> Fix GitHub Actions "No runner matching the specified labels" - a typo in runs-on, a label the runner never registered, or a removed runner group.

Source: https://latchkey.dev/learn/github-actions/gha-runner-label-no-match  
Updated: 2026-06-25

GitHub knows immediately that no registered runner can ever match the requested label set, so it fails the job instead of queuing it. The label is misspelled or was never assigned to a runner.

## 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.

```.github/workflows/ci.yml
- 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) }}"
```

> If the job sits in `queued` and never picks up, no runner matches every label you listed. Labels are ANDed: `runs-on: [self-hosted, linux, gpu]` needs one runner carrying all three, not three runners carrying one each.

## 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.

## FAQ

### What causes GitHub Actions "No runner matching the specified labels"?

There are 2 common causes: typo or wrong label in runs-on and label never registered on the runner. A misspelled or non-existent label (for example ubuntu-24.04 written as ubuntu-2404) matches no runner.

### How do I fix GitHub Actions "No runner matching the specified labels"?

There are 2 fixes depending on which cause you have: use labels your runners actually have and verify github-hosted label names. Work through them in order, since the first is the most common.

### What does GitHub Actions "No runner matching the specified labels" actually mean?

The job fails fast with a message that no runner matches the specified labels, listing the labels you requested.

### How do I stop GitHub Actions "No runner matching the specified labels" happening again?

Keep a documented list of valid runner labels for the org. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt