Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A GitHub Actions job sits queued and never starts

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

  • Applies to GitHub Actions, GitHub-hosted and self-hosted runners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/*.yml
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3The 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. 4The runner shows Offline although the machine is on. The runner application cannot reach GitHub.The runner host cannot reach GitHubFix

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

2Fix

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

3Verify

The runner shows Idle on the Runners page, then Active, and the job moves from Queued to In progress.

gh run list --limit 5

Confirmed by docs.github.com

Did this fix it?

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 page

2Fix

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 watch

Confirmed by docs.github.com

Did this fix it?

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/*.yml

2Fix

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 3

Confirmed by docs.github.com

Did this fix it?

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 folder

2Fix

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

3Verify

The check script reports PASS for every service and the runner shows Idle.

./config.sh --check --url URL --pat TOKEN

Confirmed by docs.github.com

Did this fix it?

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 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.