GitHub Actions "No runner matching the specified labels"
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.
What this error means
The job fails fast with a message that no runner matches the specified labels, listing the labels you requested. Unlike a queue wait, this is an immediate failure because the match is impossible.
Error: No runner matching the specified labels was found: self-hosted, ubuntu-24.04, arm64Diagnose 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
Typo or wrong label in runs-on
A misspelled or non-existent label (for example ubuntu-24.04 written as ubuntu-2404) matches no runner.
Label never registered on the runner
Custom labels must be added when the self-hosted runner is configured. Requesting one the runner does not carry yields no match.
How to fix it
Use labels your runners actually have
List the runner labels in settings and request exactly those, or assign the missing label to the runner.
# add a custom label when configuring a self-hosted runner
./config.sh --url https://github.com/org/repo --labels gpu,cuda
# then request it
runs-on: [self-hosted, gpu]Verify GitHub-hosted label names
- Use documented labels like ubuntu-latest, ubuntu-24.04, windows-latest, macos-latest.
- For larger runners, use the exact label configured in your runner group settings.
- Check the runner group has access to the repository requesting it.
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 a documented list of valid runner labels for the org.
- Validate runs-on labels with actionlint, which knows the hosted labels.
- Standardize custom labels when provisioning self-hosted runners.