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 (Hetzner only), images must support
arm64. - Paused in GitLab: a runner paused in GitLab takes no jobs. That is separate from pausing it in Manage Runners.
A Docker-in-Docker service does not start
On a dind runner, a job that uses GitLab’s standard docker:dind setup fails with:
Cannot connect to the Docker daemon at tcp://docker:2375
and the service log shows:
can't create unix socket /var/run/docker.sock: device or resource busy
The server’s Docker socket is already mounted into the service container. Either remove the service and DOCKER_HOST, so the job uses the server’s daemon, or keep the service and set DOCKER_HOST: unix:///runner/services/docker/docker.sock. See Docker in dind jobs.
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.
- DigitalOcean could not create the droplet or its reserved IPs for a new runner, for example because the token lacks a scope or the account reached a limit. See A DigitalOcean token or limit is refused.
- The provider token was revoked or deleted while the runner existed, and a pause, resume or SSH key lookup failed.
To recover:
- Make sure you have a working token for the runner’s provider: a Read & Write token for its Hetzner project, or a DigitalOcean token with all the scopes for its DigitalOcean account.
- For a Hetzner runner on a saved token, replace the saved token in Organization settings > Hetzner tokens: every Unknown runner that uses it is checked again on its own. Otherwise Edit the runner, choose or enter the token under Hetzner API token or DigitalOcean API Token, and save. A DigitalOcean runner that uses a connection needs no token: reconnect the team instead, and its runners are checked again on their own.
Manage Runners then checks the project or account. If the server exists, the runner becomes Active again, with Show in dashboard turned off and Send to set to None. 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 or the DigitalOcean control panel 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.
A DigitalOcean token or limit is refused
DigitalOcean’s refusals are shown with DigitalOcean’s own message:
- Invalid DigitalOcean API token when you leave the DigitalOcean API Token field: the token is wrong, expired or revoked. Create a new one as described in DigitalOcean setup.
- The API token lacks a scope Manage Runners needs: the token was created without one of the custom scopes. The token check only needs
account:readandssh_key:read, so a missing scope shows up only when an operation needs it, for example creating, pausing or deleting a droplet. If creating a new runner’s droplet fails, the runner becomes Unknown; a failed resume leaves the runner paused. Generate a token with all the scopes and enter it on the runner. - The account is locked: DigitalOcean has locked the token’s account. Resolve it with DigitalOcean.
- The DigitalOcean connection has to be reconnected: DigitalOcean no longer accepts the connection of your team, for example because the app was removed from the team. Select Reconnect under DigitalOcean access or in Organization settings > DigitalOcean connections and authorize the same team; its Unknown runners are then checked again on their own. See Connect DigitalOcean.
- DigitalOcean granted too few permissions: while connecting, a permission was removed on DigitalOcean’s page. Connect again and allow all of them.
- DigitalOcean does not offer the size in the region to your team: when you create a runner, change a runner’s size or save a burst runner template, Manage Runners asks DigitalOcean with your token whether it offers the size in the region to your team, and refuses the change if not. Nothing is saved. The sizes Manage Runners lists do not depend on your team, so there are two possible causes: your team’s tier does not allow the size, or the region has no capacity for it right now. Choose another size or region, try again later, or ask DigitalOcean support to raise your team’s tier. See Account limits.
- Droplet limit or reserved IP limit: the account may not have more droplets or reserved IPs. Every runner needs one droplet, one reserved IPv4 and one reserved IPv6; a burst runner needs only a droplet. Delete unused droplets or reserved IPs, or ask DigitalOcean to raise the limit. See Account limits.
- DigitalOcean has not released an IP yet when you delete a paused runner: DigitalOcean can take some minutes to release a reserved IPv4 after its droplet is gone. The runner is kept; delete it again a few minutes later.
- The API rate limit is reached: DigitalOcean allows a limited number of API requests per token. Try again later.
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
The provider 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.
The metrics charts show 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 or the DigitalOcean control panel.
- Metrics 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].
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.
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.