GitLab Runner Has Never Contacted This Instance: Every Cause and Fix
You created a runner, GitLab listed it, and next to it sits a grey warning: This runner has never contacted this instance. Your pipeline sits pending, and nothing in the UI tells you why. The good news is that this message is far more specific than it looks. It rules out most of what you might be about to check. What the message actually means GitLab runners poll. The runner process asks GitLab…
When you create a GitLab Runner, it appears in the UI with an authentication token starting with "glrt-". However, before installing the runner, this warning message appears: "This runner has never contacted this instance". This message is more specific than it seems, as it eliminates most potential issues. To understand the cause of this warning, we must consider two main scenarios: the runner record exists in GitLab's database, and no runner process has ever polled it.
There are several reasons why this warning may appear. First, the runner may not have been installed yet. In GitLab 16 and later versions, creating a runner in the UI results in an immediate listing with an authentication token starting with "glrt-". If you stopped after copying the token without installing the runner, this is the cause.
To check if the runner is installed, use the command "sudo systemctl status gitlab-runner" for packages or "docker ps -a | grep gitlab-runner" for containers. If the runner isn't running, inspect the logs with "sudo journalctl -u gitlab-runner -n 50 --no-pager" or "docker logs gitlab-runner".
Another possible cause is that the process is not running. Use "sudo systemctl status gitlab-runner" for packages or "docker ps -a | grep gitlab-runner" for containers to confirm the runner's status. Additionally, ensure the service is reading the correct config.toml by confirming which file it loaded and checking if the runner exists in that file. If the runner is registered in a different file, re-register it or point the service to the intended file.
The runner may not be able to reach the GitLab URL, especially when running in a different network segment or using an internal hostname, VPN-only address, or private IP. Test the URL from the runner itself using "curl -v https://gitlab.example.com/api/v4/version". For self-managed instances, ensure the URL is reachable from the runner.
Finally, verify the TLS certificate. Self-signed certificates and private CAs often fail here, so provide the CA explicitly by adding "tls-ca-file = /etc/gitlab-runner/certs/ca.crt" to the config.toml file. Remember to grant the necessary permissions to the user running the service.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
