# Troubleshooting

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

Source: https://managerunners.com/docs/manual/troubleshooting/

## 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](https://managerunners.com/docs/manual/gitlab/#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](https://managerunners.com/docs/manual/runners/#remove-an-unknown-runner) 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](https://managerunners.com/docs/manual/hetzner/#create-a-project-and-an-api-token).

## 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](https://managerunners.com/docs/manual/billing/).

## Create Runner and Edit are missing

Your role in the selected organization is **Viewer**. Ask the owner to make you an editor. See [Roles](https://managerunners.com/docs/manual/organizations/#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](https://managerunners.com/docs/manual/monitoring/#when-the-plan-ends).

## You cannot sign in

- **Account locked:** wait for the time shown on the sign-in page.
- **Forgotten password:** [reset it](https://managerunners.com/docs/manual/account-security/#reset-a-forgotten-password). Reset links expire after 15 minutes.
- **Lost authenticator app:** contact [support@managerunners.com](mailto:support@managerunners.com).

## The invitation link does not work

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](https://managerunners.com/docs/manual/organizations/#invite-members).

## CLI problems

Run `manage-runners doctor` for a read-only check of the configuration, credential and API connection. The [agent guide](https://managerunners.com/docs/cli/agents/#exit-codes) lists every exit code and error code.

## Still stuck?

Email [support@managerunners.com](mailto:support@managerunners.com) with the runner ID, the time it happened and what you saw.
