act_runner "failed to connect to instance" (URL / token) in CI

By Kaveh Alemi·Latchkey

act_runner tried to register or poll the Gitea instance and the request failed. The instance URL is unreachable from the runner, or the token is invalid, so registration never completes.

What this error means

act_runner exits during register or on daemon start with a connection error naming the instance URL, or reports the token was rejected.

level=fatal msg="failed to register runner: failed to connect to
https://gitea.example.com : dial tcp: connect: connection refused"

Common causes

The instance URL is wrong or unreachable

A typo, a private address the runner host cannot route to, or a missing scheme means the runner never reaches Gitea.

The registration token is invalid or expired

Registration tokens are short-lived; a stale or copied-wrong token is rejected even when the URL is correct.

How to fix it

Verify the instance URL and reachability

1. Confirm the exact scheme and host from a browser (https://gitea.example.com).
2. From the runner host, curl the URL to prove it is routable.
3. Re-run register with the corrected --instance value.

curl -sSf https://gitea.example.com/api/v1/version
act_runner register --no-interactive \
  --instance https://gitea.example.com --token <TOKEN>

Generate a fresh registration token

Copy a new token from the instance, org, or repo Runners settings and register again; do not reuse an old one.

act_runner register --no-interactive \
  --instance https://gitea.example.com --token <FRESH_TOKEN> --name ci-runner-1

How to prevent it

• Store the instance URL and token in the runner config, not ad hoc flags.
• Register runners promptly after generating a token so it does not expire.
• Ensure the runner host has stable network routing to the instance.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions