A GitHub Actions job sits queued and never starts
Waiting for a runner to pick up this job...Short answer
GitHub keeps a job queued until a runner that is online, idle and carries every label in runs-on can take it. So the cause is one of three: the self-hosted runner is not running, a label or group in runs-on does not match the runner, or the runner host cannot reach GitHub over HTTPS.
Fix it fast
1Find out which cause you have
Print what the job asks for, then compare it with the runners listed under Settings, Actions, Runners for the repository or organization.
grep -n -A2 "runs-on" .github/workflows/*.yml2Match what you see, then jump to its fix
- 1
The job targets self-hosted and the Runners page shows the runner as Offline, or lists no runner at all.No self-hosted runner is onlineFix - 2
The runner is Idle and online, but the job never moves. One label has a typo, or a custom label was never added.A label in runs-on is missing on every runnerFix - 3
The workflow uses a group: key with or without labels:, and the runners in that group lack the label.runs-on uses a group and labels that no runner satisfies togetherFix - 4
The runner shows Offline although the machine is on. The runner application cannot reach GitHub.The runner host cannot reach GitHubFix
- 1
What does the error look like?
Waiting for a runner to pick up this job...Queued
Cause 1 of 4
No self-hosted runner is online
1Check
A self-hosted runner only receives work while its application runs on the host. If no matching runner is online and idle, the job stays queued until one comes online.
# On a Linux runner host, find the service and check it
cat ~/actions-runner/.service
systemctl --type=service | grep actions.runner2Fix
Start the runner application on the host again and wait until Settings, Actions, Runners shows it as Idle. For a quick start by hand, run the script from the runner folder; for a service, start the service found above.
# from the runner's folder
./run.sh3Verify
The runner shows Idle on the Runners page, then Active, and the job moves from Queued to In progress.
gh run list --limit 5Confirmed by docs.github.com
Cause 2 of 4
A label in runs-on is missing on every runner
1Check
Labels are cumulative: a runner must carry every label in the array. Runners created with --no-default-labels do not get the operating system and architecture labels.
grep -n "runs-on" .github/workflows/*.yml
# compare with the labels shown next to the runner on the Runners page2Fix
Make the array match the runner, or add the missing custom label to the runner in its settings. Spell the default labels as GitHub does.
jobs:
build:
runs-on: [self-hosted, linux, x64, gpu]3Verify
Push a commit or re-run the job; it leaves the queue within seconds once a runner with all four labels is idle.
gh run watchConfirmed by docs.github.com
Cause 3 of 4
runs-on uses a group and labels that no runner satisfies together
1Check
When group and labels are both given, the runner must meet both. A runner outside the group, or inside it without the label, is not eligible.
grep -n -B1 -A4 "group:" .github/workflows/*.yml2Fix
Add the runner to the group, or drop the label (or the group) you do not need.
runs-on:
group: build-runners
labels: [linux, x64]3Verify
Re-run the job and confirm a runner in that group takes it.
gh run list --limit 3Confirmed by docs.github.com
Cause 4 of 4
The runner host cannot reach GitHub
1Check
The host must make outbound HTTPS connections on port 443, and may need github.com, api.github.com and *.actions.githubusercontent.com. If an IP allow list is on, the runner's IP address must be on it.
./config.sh --check --url URL --pat TOKEN
# prints PASS or FAIL per service; logs are in the _diag folder2Fix
Open outbound 443 to those domains in the firewall or proxy, and add the host's IP address to the allow list if your organization uses one.
# firewall or proxy change, then restart the runner
./run.sh3Verify
The check script reports PASS for every service and the runner shows Idle.
./config.sh --check --url URL --pat TOKENConfirmed by docs.github.com
How do I stop it coming back?
- Run the runner as a service so it starts after a reboot, and watch its Idle or Offline state.
- Keep one list of runner labels in your team notes and copy it into workflows instead of typing it.
- Remember that a job queued for more than 24 hours fails, so an unattended queue ends in a failure, not a wait.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
Docker push to Artifact Registry fails from GitHub Actions with a permission error
Permission 'artifactregistry.repositories.uploadArtifacts' denied on resource
The identity your workflow authenticates as lacks the permission artifactregistry.repositories.uploadArtifacts on the target repository.
4 causes, each with a fixServers
docker pull or push to ghcr.io fails with 'denied'
Error response from daemon: denied
ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.
4 causes, each with a fixServers
git says it could not read Username for https://github.com in a build or CI job
fatal: could not read Username for 'https://github.com': No such device or address
Git asked for HTTPS credentials and there was no terminal to ask on, so it gave up.
3 causes, each with a fixServers
upload-artifact fails because the artifact storage quota is full
Create Artifact Container failed: Artifact storage quota has been hit. Unable to upload any new artifacts
Uploads fail when your account's shared artifact storage is used up.
3 causes, each with a fixServers
configure-aws-credentials says no OpenID Connect provider exists for GitHub
No OpenIDConnect provider found in your account for https://token.actions.githubusercontent.com
AWS has no IAM identity provider for GitHub's token issuer in the account that holds the role.
3 causes, each with a fixServers
A local composite action in GitHub Actions cannot be found
The action folder is in the repository but the runner reports that its action.yml cannot be found
A local action is read from the checked-out repository.
3 causes, each with a fix