How to Fix GitLab Runner Registration Error

In this tutorial, you'll learn about How to Fix GitLab Runner Registration Error. We cover key concepts, practical examples, and best practices.

GitLab Runner registration fails with ERROR: Registering runner... failed or 403 Forbidden when running gitlab-runner register — the runner cannot connect to the GitLab instance or the registration token is invalid.

The Problem

ERROR: Registering runner... failed
runner=xxx status=403 Forbidden
PANIC: Failed to register the runner.

Step-by-Step Fix

Step 1: Verify the registration token

# Get the token from GitLab UI:
# Settings > CI/CD > Runners > Specific runners
# Then register:
sudo gitlab-runner register \
  --url https://gitlab.com \
  --registration-token YOUR_TOKEN \
  --executor docker

Step 2: Test network connectivity

curl -I https://gitlab.com/api/v4/runners

Expected output: HTTP/2 200

Step 3: Check existing runners

sudo gitlab-runner list

Step 4: Manually edit config

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "docker-runner"
  url = "https://gitlab.com"
  token = "YOUR_TOKEN"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"

Step 5: Restart the runner

sudo gitlab-runner restart
sudo gitlab-runner verify

Prevention Tips

• Use a project-specific runner token instead of a shared one
• Store the config.toml in version control for reproducibility
• Set RUNNER_TOKEN as an environment variable during automated provisioning
• Pin runner versions to avoid API incompatibilities

Common Mistakes with runner register

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world GITLAB code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ