If GitLab marks a runner never_contacted, it means GitLab has not recorded a contact from that runner—not that GitLab has identified the cause. The first action in GitLab’s runner management documentation is to run gitlab-runner run on the runner host. Then use the runner’s logs to locate the failing layer: process, configuration, version compatibility, or network path.
What never_contacted means
GitLab’s current runner status definitions distinguish recent contact from no recorded contact: online means contact within the last two hours, offline means no contact for more than two hours, stale means no contact for more than seven days, and never_contacted means the runner has never contacted GitLab. These are GitLab’s operational definitions, not a diagnosis of why contact failed.
As an Amazon Associate I earn from qualifying purchases.
GitLab’s immediate instruction for this status is gitlab-runner run. If the runner is managed as a service, container, or Kubernetes workload, check that actual deployment and its logs rather than assuming an interactive command or restart fixed it.
1. Check that the Runner process starts
Run the command on the machine or in the environment where GitLab Runner is installed. For a service deployment, inspect its recent logs. GitLab’s troubleshooting guide gives this systemd example:
#1 Best Overall
journalctl --unit=gitlab-runner.service -n 100 --no-pagerFor other deployments, use the corresponding runtime logs, adapting names to your setup:
- Docker:
docker logs gitlab-runner-container - Kubernetes:
kubectl logs gitlab-runner-pod
Look for startup failures, configuration parsing errors, authentication errors, connection timeouts, DNS resolution failures, or TLS certificate errors. If you have just changed configuration, restart the Runner service and tail its logs for new errors; a restart cannot correct a bad URL, token, or network route by itself. See GitLab’s troubleshooting guide for log and diagnostic context.
Rank #2
2. Verify the instance URL and runner token
Use the GitLab instance URL, not a project URL
Inspect the effective url in the runner’s config.toml. It should point to the GitLab instance root. For a project at gitlab.example.com/group/project, the instance URL is https://gitlab.example.com, not the project’s full URL. GitLab.com’s instance URL is https://gitlab.com; for self-managed GitLab, use the base URL administrators configure for that instance.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallGitLab’s runner registration guide describes the current authentication-token workflow. Confirm the runner was registered against the intended instance and through the intended project, group, or instance workflow. Registration tokens are legacy: GitLab says their use was disabled on all instances in GitLab 17.0 unless enabled, and its registration documentation schedules removal of registration tokens and several related arguments in GitLab 20.0. Check the policy for the GitLab version you actually run.
Rank #3
Protect and verify the token
Runner authentication tokens are stored in config.toml after registration. GitLab displays them in the UI only for a limited period during registration, so confirm that the configuration contains the intended credential and that it has not been replaced or exposed. Treat tokens as secrets; do not paste them into public logs, tickets, or support posts.
3. Check GitLab and Runner version compatibility
GitLab recommends checking that the GitLab and GitLab Runner versions match as an early troubleshooting step. A mismatch does not automatically explain never_contacted, so use the logs to establish whether the versions are relevant.
There is a specific documented incompatibility: Runner 15.0 changed the registration request format, preventing communication with earlier GitLab versions. If the logs and version history fit that case, use a compatible Runner version or upgrade GitLab. Consult the version notes in GitLab’s registration documentation and the troubleshooting guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
4. Trace the network path used by the Runner
Do not assume that connectivity from your shell proves connectivity from the Runner. A service account, Docker container, Kubernetes pod, and build job can each have different proxy variables, DNS, certificates, or routes. Follow the error in the Runner logs and investigate the environment that makes the GitLab API request.
Best Value
Proxy settings
If the Runner host requires an HTTP proxy to reach GitLab during registration, GitLab documents setting HTTP_PROXY and HTTPS_PROXY before running registration. Ensure those variables are available to the process or service that actually runs Runner; variables set only in an interactive shell may not reach a system service. See the registration guide and Runner configuration documentation.
Docker DNS
With the Docker executor, DNS inside containers can differ from the host’s DNS. Separate networks, VPNs, or Internet paths may cause the container to resolve or route GitLab differently. GitLab documents a dns setting under [runners.docker] in config.toml; choose a DNS server valid for your network rather than copying an example address. The troubleshooting guide covers this configuration.
TLS certificates
If logs show x509: certificate signed by unknown authority, check whether the Runner environment trusts the certificate chain used by your GitLab instance or an inspecting proxy. GitLab provides guidance for self-signed certificates in its configuration documentation. Do not disable TLS verification as a general workaround.
Intermediate proxies and correlation IDs
Runner logs include correlation IDs for API requests. GitLab says a fallback correlation ID can indicate that a request did not reach Workhorse, which points investigation toward an intermediate hop such as a WAF, CDN, load balancer, or proxy. Compare the ID in Runner logs with GitLab server logs where available, then trace the request through the intervening infrastructure. This clue narrows the failing hop; it does not by itself identify which intermediary is responsible. See GitLab’s troubleshooting documentation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.5. Check runner scope after contact is restored
GitLab supports instance, group, and project runners. A project runner must be enabled for each project that should use it, and group or instance settings can also affect job availability. Check those associations if the runner contacts GitLab but is not offered to jobs. Scope settings are a separate availability check; they do not establish why a runner host has never contacted the instance. GitLab explains runner scope in Manage runners.
Quick Recap
Choose the next check from the error
- No process or startup output: verify the service, container, or pod is running and inspect its runtime logs.
- URL or authentication error: check the instance-root URL and the credential in
config.toml. - Registration-format or compatibility error: compare GitLab and Runner versions and check the Runner 15.0 registration change.
- Timeout or name-resolution failure: inspect proxy variables, DNS, routes, and intermediary infrastructure from the Runner’s own environment.
- Certificate authority error: configure trust for the certificate chain instead of bypassing TLS validation.
- Runner is online but jobs cannot use it: check project, group, or instance scope and enablement.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
