GitHub Actions "No runner matching the specified labels was found"

By Daniel Zoghalchali·Latchkey

The workflow requested a label set that no online self-hosted runner advertises, so GitHub has nowhere to send the job and reports the mismatch immediately.

What this error means

The job fails to start with "No runner matching the specified labels was found: self-hosted, <label>". The Settings > Actions > Runners page shows no online runner with that exact label combination.

No runner matching the specified labels was found: self-hosted, linux, gpu

Common causes

Label typo or missing custom label

A custom label in runs-on (gpu, arm64, build-large) is misspelled or was never added to any runner, so the AND of all requested labels matches nothing.

The matching runner is offline

A runner that would match is registered but not connected, so it cannot be selected and the request resolves to no match.

How to fix it

Align labels with a registered runner

1. List runners under Settings > Actions > Runners and note their labels.
2. Make runs-on an exact subset of one online runner's labels.
3. Add any missing custom label to the runner via ./config.sh --labels.
4. Confirm the runner shows Idle (green) before re-running.

jobs:
  build:
    runs-on: [self-hosted, linux, gpu]

How to prevent it

• Document the canonical label set for each self-hosted pool.
• Lint runs-on against known labels in review.
• Alert when a labeled runner goes offline so jobs do not silently fail to match.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions