Forgejo Runner version incompatible with instance in CI

The Forgejo Runner and the Forgejo instance speak a versioned Actions protocol. A runner far behind or ahead of the instance can be refused at registration or fail while claiming tasks. Align the runner version with the instance.

What this error means

The Forgejo Runner fails to register or repeatedly errors when fetching tasks after a Forgejo upgrade, while the URL and token are correct.

level=error msg="failed to fetch task: unsupported runner version"
# Forgejo Runner too old (or too new) for this instance

Common causes

The runner is older than the instance requires

After upgrading Forgejo, an old runner may not support the current protocol and gets refused.

The runner is newer than the instance supports

A runner ahead of the instance can expect endpoints the older instance does not serve.

How to fix it

Upgrade the runner to match the instance

1. Check the Forgejo instance version.
2. Install a Forgejo Runner release compatible with it.
3. Restart the runner and confirm it registers and fetches tasks.

forgejo-runner --version
# install a compatible release, then:
systemctl restart forgejo-runner

Pin runner and instance versions together

Roll the runner and instance in lockstep so the protocol never drifts across an upgrade.

# upgrade runner in the same maintenance window as the instance

How to prevent it

• Upgrade runners alongside the instance.
• Track the compatible runner version for your instance release.
• Verify task fetch works right after any upgrade.

Related guides