How to Fix “Waiting for a Runner to Pick Up This Job” Error in GitHub Actions

GitHub Actions is a powerful tool for automating your CI/CD workflows, but it’s not without its hiccups. One common issue that frustrates developers is the GitHub Actions runner error: “Waiting for a runner to pick up this job.” This error means your workflow is stuck in the queue, unable to execute because no runner is available to process it. If you’re seeing this message, don’t panic! This guide will explain why this happens, how to fix it, and how to prevent it in the future.

Whether you’re using GitHub-hosted runners or self-hosted runners, we’ll cover GitHub Actions troubleshooting step by step. By the end, you’ll have a clear path to resolve this error and keep your pipelines running smoothly. Let’s dive in!

What Does “Waiting for a Runner to Pick Up This Job” Mean?

In GitHub Actions, a runner is a virtual machine or server that executes your workflow jobs. Runners can be:

• GitHub-hosted runners: Cloud-based virtual machines managed by GitHub (e.g., ubuntu-latest, windows-latest).
• Self-hosted runners: Machines you set up and manage, often for custom environments or private networks.

The error “Waiting for a runner to pick up this job” appears when GitHub Actions can’t find an available runner to execute your job. This could happen for several reasons, like a typo in your workflow file, an offline self-hosted runner, or high demand on GitHub’s servers. Understanding the cause is the first step to fixing it.

Why Does the GitHub Actions Runner Error Happen?

Here are the most common reasons for the Waiting for a runner error, based on community discussions and GitHub documentation:

• Typo in runs-on Label: A misspelled or invalid runner label (e.g., ubuntu-latst instead of ubuntu-latest) causes GitHub to wait indefinitely for a non-existent runner.
• Unsupported Operating System: Using a deprecated OS (e.g., ubuntu-18.04, unsupported since April 2025) prevents runners from picking up the job.
• Busy Runners: GitHub-hosted runners may be overloaded during peak usage, especially on free plans.
• Self-Hosted Runner Issues: Self-hosted runners may be offline, misconfigured, or stuck due to network or permission problems.
• Workflow Syntax Errors: Incorrect YAML syntax or conflicting job dependencies can stall the workflow.
• Concurrency Limits: Free or limited GitHub accounts may hit concurrent runner limits, queuing jobs until runners are free.
• GitHub Service Issues: Temporary outages or degraded performance on GitHub’s end can delay runner assignment.

Now, let’s explore how to troubleshoot and fix this error step by step.

Step-by-Step Solutions to Fix the GitHub Actions Runner Error

Step 1: Check Your runs-on Label for Typos

The most common cause of the GitHub Actions runner error is a typo in the runs-on key in your workflow YAML file. GitHub Actions doesn’t validate runner labels, so a misspelled label (e.g., unbuntu-latest or self-hosted instead of [self-hosted, my-label]) will cause the job to wait forever.

How to Fix It:

• Open your workflow file (e.g., .github/workflows/ci.yml).
• Locate the runs-on key under the job definition. For example:jobs: build: runs-on: ubuntu-latest
• Ensure the label is correct. Common GitHub-hosted runner labels in 2025 include:
  • ubuntu-latest (currently Ubuntu 22.04)
  • windows-latest
  • macos-latest
• For self-hosted runners, verify the exact label matches what’s configured in your repository settings (e.g., [self-hosted, linux, my-runner]).
• Fix any typos and push the updated workflow file.

Example Fix:

# Before (typo)
runs-on: ubuntu-latst

# After
runs-on: ubuntu-latest

Pro Tip: GitHub could improve this by validating runs-on labels and throwing an error for invalid ones, as many developers have suggested.

Step 2: Verify the Operating System Is Supported

GitHub regularly deprecates older runner operating systems. For example, ubuntu-18.04 was fully unsupported by April 2025, causing jobs to hang if specified.

How to Fix It:

• Check GitHub’s documentation for supported runners.
• Update your workflow to use a supported OS, such as ubuntu-latest or ubuntu-22.04.
• Example:# Before (unsupported) runs-on: ubuntu-18.04 # After runs-on: ubuntu-latest

Note: Always check GitHub’s changelog or blog for deprecation notices to stay ahead of OS changes.

Step 3: Check GitHub’s Service Status

Sometimes, the Waiting for a runner error is caused by issues on GitHub’s end, such as service outages or high demand on hosted runners.

How to Fix It:

• Visit GitHub Status to check for ongoing issues with GitHub Actions.
• If there’s an outage, wait for GitHub to resolve it.
• If no outage is reported but the job is still stuck, try canceling and re-running the workflow. Some users report that re-running resolves transient issues.

Pro Tip: Free GitHub accounts may experience longer queues during peak times. Consider upgrading to a Pro or Team plan for faster runner access.

Step 4: Troubleshoot Self-Hosted Runner Issues

If you’re using self-hosted runners, the error could stem from configuration or connectivity problems. Common issues include offline runners, permission errors, or runners stuck in an idle state.

How to Fix It:

• Check Runner Status:
  • Go to your repository or organization settings: Settings > Actions > Runners.
  • Verify that your self-hosted runner is listed and shows as Idle or Active. If it’s Offline, the runner isn’t connected to GitHub.
• Restart the Runner:
  • On the runner machine, stop and restart the runner service:./svc.sh stop ./svc.sh start
  • Alternatively, run the runner manually to check for errors:./run.sh
• Verify Network Connectivity:
  • Ensure the runner machine has internet access and can communicate with GitHub’s servers.
  • Run a connectivity check:./run.sh --check --url <your-org-url> --pat <your-personal-access-token>
• Check Runner Logs:
  • Logs are located in the runner’s _diag folder (e.g., Runner_*.log or Worker_*.log).
  • Look for errors like permission issues or connection failures.
• Recreate the Runner:
  • If the runner is stuck or corrupted, remove it from the GitHub UI and re-register it:
    • Go to Settings > Actions > Runners, delete the runner.
    • Follow GitHub’s self-hosted runner setup guide to add a new one.

Example Self-Hosted Workflow:

jobs:
  build:
    runs-on: [self-hosted, linux]
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on self-hosted runner!"

Note: Ensure your self-hosted runner’s labels match exactly in the runs-on field.

Step 5: Check Workflow Syntax and Dependencies

Syntax errors or conflicting job dependencies in your YAML file can prevent runners from picking up jobs.

How to Fix It:

• Validate your workflow file for syntax errors using a YAML linter or GitHub’s workflow editor.
• Check for conflicting actions using the needs keyword, which specifies job dependencies:jobs: build: runs-on: ubuntu-latest steps: - run: npm run build test: runs-on: ubuntu-latest needs: build steps: - run: npm run test
• Ensure no jobs are stuck due to concurrency settings:concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true

Pro Tip: Use GitHub’s Actions logs to identify syntax errors or missing dependencies.

Step 6: Add a Timeout for Stuck Jobs

To prevent jobs from waiting indefinitely, add a timeout-minutes parameter to your workflow. Note that this only applies once a runner starts the job, not while it’s queued. For queue timeouts, self-hosted runners can use the idle_timeout setting.

How to Fix It:

• Add a timeout to your job:jobs: build: runs-on: ubuntu-latest timeout-minutes: 30 steps: - run: echo "Job will timeout after 30 minutes"
• For self-hosted runners, modify the runner’s configuration file to set an idle_timeout (consult GitHub’s documentation for details).

Step 7: Increase Runner Availability

If you’re hitting runner limits (common on free plans), jobs may queue until runners are free.

How to Fix It:

• For GitHub-Hosted Runners:
  • Upgrade your GitHub plan (Pro, Team, or Enterprise) for more concurrent runners.
  • Add multiple runner types to your workflow to increase availability:runs-on: [ubuntu-latest, windows-latest, macos-latest]
• For Self-Hosted Runners:
  • Add more runners to your repository or organization. Follow GitHub’s guide to add self-hosted runners.
  • Use runner groups to manage multiple runners efficiently.

Step 8: Monitor and Debug with Logs

GitHub Actions logs provide clues about why a job is stuck. Check both the workflow logs and runner logs (for self-hosted runners).

How to Fix It:

• In the GitHub UI, go to Actions > [Your Workflow] > [Job Name] and click to view logs.
• Look for messages like:
  • “No runner matching the specified labels was found” (indicates a label issue).
  • “Job is waiting for a hosted runner to come online” (suggests high demand or service issues).
• For self-hosted runners, check the _diag folder logs for errors like permission issues or network failures.

Pro Tip: Enable debug logging in your workflow for more detailed output:

env:
  ACTIONS_RUNNER_DEBUG: true

Best Practices to Prevent the GitHub Actions Runner Error

To avoid the Waiting for a runner error in the future, follow these GitHub Actions troubleshooting tips:

• Validate runs-on Labels: Double-check for typos and use supported runner labels.
• Stay Updated: Monitor GitHub’s changelog for OS deprecations and runner updates.
• Monitor Runner Status: Regularly check self-hosted runner status in the GitHub UI.
• Use Concurrency Controls: Limit concurrent jobs to avoid overwhelming runners:concurrency: group: ${{ github.workflow }} cancel-in-progress: true
• Set Timeouts: Add timeout-minutes to jobs and idle_timeout to self-hosted runners.
• Automate Runner Health Checks: Create a workflow to check runner status periodically.
• Scale Runners: Add more self-hosted runners or upgrade your GitHub plan for high-traffic projects.

Runner Comparison Table

FAQs About the GitHub Actions Runner Error

Why is my job stuck even with ubuntu-latest?

This could be due to high demand on GitHub’s runners, a service outage, or a subtle typo. Check GitHub Status and re-run the job.

How do I know if my self-hosted runner is offline?

Go to Settings > Actions > Runners in your repository. If the runner is marked Offline, restart the runner service or recreate it.

Can I use multiple runners for one job?

Yes, specify multiple runners in runs-on (e.g., [ubuntu-latest, windows-latest]). The job will run on the first available runner.

How long should I wait for a runner?

For GitHub-hosted runners, jobs typically start within minutes. If it’s longer than 10-20 minutes, check for errors or service issues.

Get Your GitHub Actions Back on Track

The GitHub Actions runner error “Waiting for a runner to pick up this job” can be frustrating, but it’s usually fixable with a few checks. Start by verifying your runs-on label, ensuring your OS is supported, and checking runner status. For persistent issues, dive into logs, add timeouts, or scale your runners. By following the steps in this guide, you’ll resolve the error and optimize your CI/CD pipeline for 2025.

Got a stuck job? Try these steps and share your experience in the comments below. Happy automating!

Resource: For more help, visit GitHub’s Actions Documentation.