GitHub Actions setup-go "Unable to find Go version"
actions/setup-go resolves go-version (or go-version-file) against the official Go release feed. A non-existent version, or a go.mod that pins a toolchain with no published build, fails resolution.
What this error means
A setup-go step fails resolving the version, often after a typo, a yanked patch, or a go.mod toolchain line pointing at an unreleased version.
Error: Unable to find Go version '1.23.99' for platform linux and architecture amd64.Diagnose it: is the job queued, or is the runner gone?
A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.
- name: Runner facts
run: |
echo "runner name: $RUNNER_NAME"
echo "os/arch: $RUNNER_OS/$RUNNER_ARCH"
nproc; free -h; df -h /
echo "labels this job asked for: ${{ toJSON(job) }}"Common causes
Version not in the Go release feed
setup-go matches against published Go releases; a version that was never released for the platform cannot be found.
go-version-file points at an unpublished toolchain
A go.mod toolchain directive or .go-version file requesting an unreleased version drives the same failure.
How to fix it
Pin a published version or use a range
- Use a minor spec like 1.23.x so setup-go selects the newest published patch.
- If using go-version-file, confirm the toolchain in go.mod is released.
- Avoid hand-typed exact patches that may not exist.
- uses: actions/setup-go@v5
with:
go-version: '1.23.x'The failures that are not your workflow
- Exit 137 is the kernel out-of-memory killer, not an application error. Check
free -habove against your peak usage. - Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
- A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
- A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.
How to prevent it
- Prefer a minor range (1.23.x) over an exact patch in CI.
- Keep go.mod toolchain and the workflow go-version aligned.
- Latchkey managed runners auto-retry the Go download on transient network failures and keep recent toolchains in a warm cache.