How to fix This job is stuck because the project doesn't have any runners online in Git

GitINTERMEDIATEHIGHUpdated Dec 6, 2025· 453 views

This GitLab CI/CD error occurs when your pipeline job cannot find an available runner to execute it. The issue is typically caused by missing runner registration, tag mismatches, or disabled shared runners. To fix it, verify your runner configuration, enable shared runners, or register a new runner for your project.

Quick fix

Fixes This job is stuck because the project doesn't have any runners online

# You should see:
Shared runners
Enable shared runners for this project: [ON]
Available shared runners: X

Check if shared runners are enabled
Verify runner status in project settings
Fix runner tag mismatches
Register a new project runner

git — error

$# You should see:
Shared runners
Enable shared runners for this project: [ON]
Available shared runners: X
This job is stuck because the project doesn't have any runners online

What this error means

When you see "This job is stuck because the project doesn't have any runners online assigned to it," GitLab is telling you that no runner is available to execute your CI/CD job. Runners are the agents that actually run the scripts defined in your `.gitlab-ci.yml` file. GitLab CI/CD requires at least one runner to be available and properly configured to execute pipeline jobs. Without an active runner, jobs will remain in a "pending" state indefinitely, blocking your entire pipeline. There are two types of runners in GitLab: - **Shared runners**: Provided by GitLab.com or your GitLab administrator, available to all projects - **Project-specific runners**: Dedicated runners registered specifically for your project or group This error means either no runners exist, existing runners are offline, runners don't match your job's tag requirements, or shared runners are disabled for your project. The job will stay stuck until a compatible runner becomes available.

Typical symptoms

Pipeline job shows 'pending' status with clock icon indefinitely
Job displays warning: 'This job is stuck because the project doesn't have any runners online'
Pipeline progress bar stays at 0% with jobs not starting
Merge requests blocked waiting for pipeline to complete
CI/CD settings show no runners or all runners as offline
Job tooltip shows 'Waiting for a runner to pick up this job'
Email notification: 'Pipeline is stuck' or no pipeline completion emails
New commits don't trigger pipeline execution
Job displays: 'This job is stuck because you don't have any active runners online with any of these tags assigned'

Common causes

Shared runners are disabled for the project (most common on GitLab.com)
No runners registered for the project - runner was never set up
Runner service is not running - gitlab-runner process has stopped
Runner tag mismatch - job requires tags that no runner has
Runner was registered without sudo (user-mode) and cannot pick up jobs
Runner registration token expired or was revoked
Runner is offline or disconnected from GitLab server
All available runners are busy executing other jobs
Runner's executor (Docker, shell, etc.) is misconfigured
Network connectivity issues between runner and GitLab instance
Runner version incompatibility with GitLab server version
Protected branch/tag settings restrict which runners can run jobs
Runner exceeds maximum job limit or concurrent job capacity

How to fix "This job is stuck because the project doesn't have any runners online"

1Check if shared runners are enabled

The most common cause on GitLab.com is that shared runners are disabled. Enable them:

1. Go to your project in GitLab
2. Navigate to Settings > CI/CD
3. Expand the Runners section
4. Look for "Shared runners" at the bottom
5. Toggle Enable shared runners for this project to ON

text

# You should see:
Shared runners
Enable shared runners for this project: [ON]
Available shared runners: X

Note: On GitLab.com free tier, shared runners have usage limits. Check Settings > Usage Quotas to ensure you haven't exceeded your CI/CD minutes.

For self-managed GitLab, ask your administrator if shared runners are available.

2Verify runner status in project settings

Check if any runners are assigned to your project:

1. Go to Settings > CI/CD
2. Expand the Runners section
3. Review the available runners

You should see one of these sections:
- Assigned project runners - Runners specific to this project
- Assigned group runners - Runners shared within your group
- Shared runners - GitLab-provided runners

For each runner, check:
- Green circle: Runner is online and available
- Gray circle: Runner is offline
- Warning icon: Runner has configuration issues

text

# Healthy runner display:
Runner #12345 (my-runner)
Status: online
Tags: docker, linux

If no runners appear or all are offline, you need to register a new runner or troubleshoot existing ones.

3Fix runner tag mismatches

If your job specifies tags but no runner has those tags, the job will be stuck:

Check your .gitlab-ci.yml for tags:

yaml

# This job requires a runner with 'docker' and 'linux' tags
build:
  tags:
    - docker
    - linux
  script:
    - echo "Building..."

Option 1: Remove tags to use any available runner:

yaml

build:
  # No tags - any runner can pick this up
  script:
    - echo "Building..."

Option 2: Configure runner to accept untagged jobs:
1. Go to Settings > CI/CD > Runners
2. Click the pencil/edit icon on your runner
3. Enable Run untagged jobs
4. Click Save changes

Option 3: Add matching tags to your runner:
1. Edit your runner's config.toml:

toml

[[runners]]
  name = "my-runner"
  tags = ["docker", "linux"]

2. Or update tags in GitLab UI under runner settings

Option 4: Use available tags in your job:

yaml

build:
  tags:
    - saas-linux-small-amd64  # GitLab.com shared runner tag
  script:
    - echo "Building..."

4Register a new project runner

If you need a dedicated runner for your project, register one:

Step 1: Get registration token
1. Go to Settings > CI/CD > Runners
2. Click New project runner
3. Configure runner options (tags, description)
4. Click Create runner
5. Copy the registration token shown

Step 2: Install GitLab Runner

bash

# Linux (Debian/Ubuntu)
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt-get install gitlab-runner

# Linux (RHEL/CentOS/Fedora)
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh" | sudo bash
sudo yum install gitlab-runner

# macOS
brew install gitlab-runner

# Windows (PowerShell as Administrator)
# Download from https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe

Step 3: Register the runner (GitLab 17.5+)

bash

# IMPORTANT: Use sudo for system-mode runner
sudo gitlab-runner register \
  --url https://gitlab.com \
  --token YOUR_REGISTRATION_TOKEN

# Follow the prompts to configure:
# - Description: my-project-runner
# - Tags: docker,linux (optional)
# - Executor: docker, shell, etc.

Step 4: Start the runner service

bash

# Install and start as system service
sudo gitlab-runner install
sudo gitlab-runner start

# Verify it's running
sudo gitlab-runner status

5Troubleshoot offline runners

If your runner shows as offline, check these common issues:

Verify the runner service is running:

bash

# Check service status
sudo gitlab-runner status

# If not running, start it
sudo gitlab-runner start

# View runner logs for errors
sudo gitlab-runner --debug run

Check if runner was registered in user mode:

bash

# List all registered runners
gitlab-runner list

# If registered without sudo, re-register with sudo
sudo gitlab-runner register

Verify network connectivity:

bash

# Test connection to GitLab
curl -v https://gitlab.com/api/v4/version

# For self-managed GitLab
curl -v https://your-gitlab-instance.com/api/v4/version

Check runner configuration:

bash

# View config file
cat /etc/gitlab-runner/config.toml

# Verify token is valid
# The runner should show as "online" in GitLab UI

Restart the runner:

bash

sudo gitlab-runner restart

# Or stop and start
sudo gitlab-runner stop
sudo gitlab-runner start

6Check runner executor configuration

Ensure your runner's executor is properly configured:

Docker executor issues:

bash

# Verify Docker is running
docker info

# Check runner config for Docker executor
cat /etc/gitlab-runner/config.toml

toml

# config.toml should have:
[[runners]]
  name = "my-runner"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    volumes = ["/cache"]

Shell executor issues:

toml

[[runners]]
  name = "my-runner"
  executor = "shell"
  shell = "bash"

Common Docker executor fixes:

bash

# Add gitlab-runner user to docker group
sudo usermod -aG docker gitlab-runner

# Restart Docker and runner
sudo systemctl restart docker
sudo gitlab-runner restart

Test runner can execute jobs:

bash

# Verify runner by running a test
sudo gitlab-runner verify

7Handle busy runners

If all runners are busy with other jobs, you may need to wait or add capacity:

Check runner concurrency:

toml

# /etc/gitlab-runner/config.toml
concurrent = 4  # Increase to allow more parallel jobs

[[runners]]
  name = "my-runner"
  limit = 0  # 0 = unlimited, or set a specific limit

Monitor runner capacity:
1. Go to Admin Area > CI/CD > Runners (self-managed)
2. Or Settings > CI/CD > Runners (project level)
3. Check how many jobs each runner is processing

Add more runners:
- Register additional runners on the same or different machines
- Consider using autoscaling runners for variable workloads

Prioritize critical jobs:

yaml

# Lower numbers = higher priority (run first)
critical_build:
  tags:
    - docker
  resource_group: production
  script:
    - ./deploy.sh

Cancel stuck or unnecessary jobs:
1. Go to Build > Pipelines
2. Find running pipelines using resources
3. Click Cancel on non-essential jobs

8Retry the stuck job

Once you've fixed the runner configuration, retry your stuck job:

Manual retry:
1. Go to your pipeline in Build > Pipelines
2. Click on the stuck/pending job
3. Click Cancel to stop the stuck job
4. Click Retry or Run to restart it

Retry entire pipeline:
1. Navigate to the pipeline
2. Click Retry button (circular arrow) at the top
3. Or push a new commit to trigger a fresh pipeline:

bash

git commit --allow-empty -m "ci: retry pipeline"
git push origin your-branch

Verify job is picked up:
- Job should change from "pending" to "running" within seconds
- Runner name appears in job sidebar showing which runner picked it up
- Log output starts appearing as the job executes

If job is still stuck:
1. Clear runner cache: Settings > CI/CD > General pipelines > Clear runner caches
2. Check if runner went offline again
3. Verify tag configuration matches

Advanced notes

### Runner Registration Methods (GitLab 15.10+)

GitLab now supports two registration methods:

Runner authentication tokens (Recommended):

bash

# Create runner in GitLab UI first, then:
sudo gitlab-runner register --url https://gitlab.com --token glrt-XXXXX

Legacy registration tokens (Deprecated):

bash

# Will be removed in future GitLab versions
sudo gitlab-runner register --registration-token XXXXX

### System Mode vs User Mode (GitLab 17.5+)

As of GitLab 17.5, how you register determines the runner's mode:

System mode (recommended for CI/CD):

bash

sudo gitlab-runner register  # Uses system-wide config
sudo gitlab-runner install   # Installs as system service
sudo gitlab-runner start

User mode (manual execution required):

bash

gitlab-runner register  # Without sudo
gitlab-runner run       # Must manually run to pick up jobs

### Protected Runners

For sensitive jobs (production deployments), use protected runners:

yaml

# .gitlab-ci.yml
deploy_production:
  tags:
    - protected
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == "true"
  script:
    - ./deploy.sh production

Configure runner as protected:
1. Go to Settings > CI/CD > Runners
2. Edit the runner
3. Enable Protected option
4. Save changes

Protected runners only run jobs on protected branches/tags.

### Autoscaling Runners

For variable workloads, consider autoscaling:

toml

# config.toml with Docker Machine autoscaling
[[runners]]
  name = "autoscale-runner"
  executor = "docker+machine"
  [runners.machine]
    IdleCount = 1
    IdleTime = 600
    MaxBuilds = 100
    MachineDriver = "amazonec2"
    MachineName = "gitlab-runner-%s"

### Runner Version Compatibility

Keep runner version aligned with your GitLab version:

| GitLab Version | Recommended Runner Version |
|----------------|---------------------------|
| 17.x | 17.x |
| 16.x | 16.x |
| 15.x | 15.x |

bash

# Check runner version
gitlab-runner --version

# Update runner (Debian/Ubuntu)
sudo apt-get update
sudo apt-get upgrade gitlab-runner

### Monitoring Runner Health

Monitor your runners to prevent future issues:

yaml

# Prometheus metrics endpoint in config.toml
listen_address = ":9252"

Key metrics to monitor:
- gitlab_runner_jobs_total - Total jobs processed
- gitlab_runner_concurrent - Current concurrent jobs
- gitlab_runner_limit - Maximum concurrent jobs allowed

### Troubleshooting Runner Logs

bash

# View runner logs
sudo journalctl -u gitlab-runner -f

# Debug mode for verbose output
sudo gitlab-runner --debug run

# Check for specific errors
sudo journalctl -u gitlab-runner | grep -i "error\|failed"

Common log errors and fixes:
- "certificate signed by unknown authority": Add CA cert to runner config
- "dial tcp: connection refused": Check network/firewall settings
- "job timed out": Increase job timeout in .gitlab-ci.yml
- "no free executors": Increase runner concurrency

Frequently asked questions

What does "This job is stuck because the project doesn't have any runners online" mean?: When you see "This job is stuck because the project doesn't have any runners online assigned to it," GitLab is telling you that no runner is available to execute your CI/CD job. yml file. GitLab CI/CD requires at least one runner to be available and properly configured to execute pipeline jobs.
How do I fix "This job is stuck because the project doesn't have any runners online"?: This GitLab CI/CD error occurs when your pipeline job cannot find an available runner to execute it. The issue is typically caused by missing runner registration, tag mismatches, or disabled shared runners. To fix it, verify your runner configuration, enable shared runners, or register a new runner for your project.
What causes "This job is stuck because the project doesn't have any runners online"?: Shared runners are disabled for the project (most common on GitLab.com) No runners registered for the project - runner was never set up Runner service is not running - gitlab-runner process has stopped
Is the "This job is stuck because the project doesn't have any runners online" error serious?: Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading

📚Git Official Documentation
📖
GitLab Docs - GitLab Runner(Official Docs)
📖
GitLab Docs - Install GitLab Runner(Official Docs)
📖
GitLab Docs - Runner Configuration(Official Docs)
📖
GitLab Docs - CI/CD Runners(Official Docs)
💬
Stack Overflow - Job Stuck No Runners(Stack Overflow)
💬
GitLab Forum - Runners Not Online(Stack Overflow)

How to fix This job is stuck because the project doesn't have any runners online in Git

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "This job is stuck because the project doesn't have any runners online"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading