how to debug GitLab runner registration token errors

TL;DR

Runner registration failures are token-scope problems far more often than network problems: the token belongs to the wrong level (instance, group, or project) or has been rotated. Get a fresh token from the right settings page (Admin for instance runners, group or project Settings then CI/CD then Runners), and register with the matching scope. A token from the wrong level fails with an unhelpful generic error.

Error / query

how to debug GitLab runner registration token errors

Use this skill when

• gitlab-runner register fails with a token error
• A runner registers but never contacts GitLab
• Registration worked before and suddenly broke
• You are unsure which token a runner needs

Not for this skill when

• Jobs fail after the runner is registered (executor problem)
• The runner binary will not install (installation problem)
• GitLab itself is down or unreachable (server problem)

Steps

Step 1: Get the token from the correct level

# instance runners: Admin area, then Runners
# group runners: group Settings, then CI/CD, then Runners
# project runners: project Settings, then CI/CD, then Runners

Expected: a registration token (or registration flow) for exactly the scope the runner should serve. Instance tokens register shared runners; project tokens register project-only runners. Mixing levels is the top cause of failures.

Step 2: Register non-interactively with explicit scope

gitlab-runner register --non-interactive --url "https://YOUR-gitlab-host/" --registration-token "[token-value]" --executor "docker" --docker-image "alpine:latest" --description "[runner-name]" --tag-list "[tags]" --run-untagged="false"

Expected: Runner registered successfully. The --url must match the GitLab external URL exactly (scheme, host, port); a mismatch here produces token-looking errors.

Step 3: Verify the runner checks in

gitlab-runner verify
# and in GitLab: Settings, then CI/CD, then Runners, look for a green dot

Expected: the runner shows as active with a recent contact time. verify confirms the stored token still authenticates; if it fails after a success, the token was rotated or revoked.

Step 4: Handle rotated or revoked tokens

gitlab-runner unregister --name "[runner-name]"
# then re-run the register command from step 2 with the new token

Expected: clean re-registration. Tokens rotate on GitLab upgrades and admin actions; when many runners fail at once, rotation (not individual runner breakage) is the cause. Re-register rather than debugging each runner's config.

Variant phrasings

"gitlab runner invalid registration token"

Steps 1-2. Nine times out of ten the token came from the wrong scope level.

"gitlab-runner register fails"

Check the URL (step 2) and token scope (step 1) before anything else.

Why it happens

GitLab has three token scopes that look identical but are not interchangeable, and the registration error does not say which scope it expected. Add token rotation on upgrades and admin resets, plus URL mismatches that surface as auth failures, and registration becomes the most failure-prone five minutes of runner setup.

Edge cases and pitfalls

• Newer GitLab versions moved toward runner creation workflows with authentication tokens instead of shared registration tokens; check your version's docs.
• A runner behind a proxy needs HTTP_PROXY set for the register call too, not just for jobs.
• --run-untagged="false" with no matching tags means the runner idles forever; that looks like a registration problem but is a tag problem.
• config.toml from a previous registration can shadow new values; unregister fully before re-registering.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ywpvguejWBVSjcgYCZWyag