Manage Runners Logo
Manage Runners
Documentation menu
View as Markdown

Troubleshooting

What to do when a runner is stuck, unknown or rejected, jobs don't start, or the dashboard refuses an action.

Jobs stay pending

The runner is Active but GitLab does not give it jobs.

  • Tags: a job only runs on a runner that has all of the job’s tags. Compare the job’s tags: with the runner’s tags in GitLab under Settings > CI/CD > Runners. Jobs without tags need Run untagged jobs on the runner.
  • Scope: a project runner only takes jobs of its project. Use a group runner to serve several projects.
  • Architecture: on an ARM server, images must support arm64.
  • Paused in GitLab: a runner paused in GitLab takes no jobs. That is separate from pausing it in Manage Runners.

The runner shows Invalid Gitlab Token

GitLab rejected the token when the server registered. The server keeps running and costs money while the runner is in this state. Select Fix, paste a valid runner authentication token, check the GitLab host, and select Save. See When GitLab rejects the token.

A runner is Unknown

A runner becomes Unknown when Manage Runners can no longer tell what happened to its server. Common causes:

  • Hetzner could not create the server for a new runner, for example because the token is read-only or Hetzner had no capacity.
  • The Hetzner token was revoked or deleted while the runner existed, and a pause, resume or SSH key lookup failed.

To recover:

  1. Make sure you have a working Read & Write token for the runner’s Hetzner project.
  2. Edit the runner, enter the token in Hetzner Auth Token, and save.

Manage Runners then checks the project. If the server exists, the runner becomes Active again, with monitoring turned off. If it does not, the runner becomes Paused, and you can resume it.

If you no longer need the runner, remove it and clean up the server and IP addresses in the Hetzner Console yourself.

Hetzner could not create the server

Resuming a runner can fail with an error saying that Hetzner responded with HTTP 412. This usually means Hetzner has no capacity for that server type in that location at the moment. The runner stays Paused. Try again later, or edit the runner to use another server type. A new runner in another location is the other option, since a runner’s location cannot change.

The Hetzner token is rejected

When you leave the Hetzner Auth Token field, the dashboard checks the token by listing the project’s SSH keys. If it shows an error, the token is wrong, revoked or belongs to a project that no longer exists. Create a new token as described in Hetzner setup.

An action fails because the runner is locked

Only one lifecycle action, such as pause, resume or delete, runs on a runner at a time. Wait until the runner has reached a stable state, then try again.

Resume or Duplicate is disabled

Hetzner no longer offers the runner’s server type in its location. Edit the runner to choose an available server type, or create a new runner.

The dashboard opens Billing

The selected organization has no active plan. Its owner can choose one under Billing. If you belong to several organizations, switch to another one with the menu at the top. See Billing and plans.

Create Runner and Edit are missing

Your role in the selected organization is Viewer. Ask the owner to make you an editor. See Roles.

Monitoring shows no data

  • Waiting for first data: values appear a few minutes after the server starts.
  • No data for some minutes: the server may be rebooting after automatic updates, or it is overloaded. Check it in the Hetzner Console.
  • Monitoring paused: the organization’s plan is not active. See When the plan ends.

You cannot sign in

  • Account locked: wait for the time shown on the sign-in page.
  • Forgotten password: reset it. Reset links expire after 15 minutes.
  • Lost authenticator app: contact [email protected].

Invitation links work once and expire after a week. The invitation must be accepted with an account whose email address matches it. Ask the owner to resend the invitation. See Invite members.

CLI problems

Run manage-runners doctor for a read-only check of the configuration, credential and API connection. The agent guide lists every exit code and error code.

Still stuck?

Email [email protected] with the runner ID, the time it happened and what you saw.