Go: module requires go >= 1.x (running go 1.y)

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

go version

# Let Go fetch the right toolchain (default behaviour)
go env -w GOTOOLCHAIN=auto

# Or install explicitly
go install golang.org/dl/go1.24.0@latest && go1.24.0 download

# In CI, pin the Go version rather than relying on the runner image
# actions/setup-go with go-version-file: go.mod

How to diagnose Go errors

Go's runtime is unusually good at telling you what went wrong. concurrent map writes and all goroutines are asleep - deadlock! are precise diagnoses rather than vague crashes. The recurring themes are nil zero values that need explicit initialisation (maps, channels, pointers inside interfaces), unsynchronised shared state, and contexts that are cancelled upstream.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Run tests and, where possible, production builds under the race detector: go test -race ./.... It finds data races that are invisible under normal execution.
2. Read the full panic output. Go prints every goroutine's stack, and the one that matters is usually not the first.
3. For context canceled, walk up the call chain to find who cancelled: a client disconnect, a timeout, or a parent context that went out of scope are the three sources.
4. Distinguish a nil interface from an interface holding a nil pointer. var p *T = nil; var i I = p makes i != nil, which is the cause of most "interface conversion: interface is nil" surprises.
5. Use go tool pprof and runtime.NumGoroutine() to find goroutine leaks. A count that only ever grows means something is never returning.

Tools worth reaching for

• go test -race
• go vet
• go tool pprof
• GODEBUG=gctrace=1
• delve (dlv)

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 go.dev

Related Go errors

• cannot find module providing packageGo cannot resolve a package import. The module may not be downloaded, the import path may be…
• context canceledA context was cancelled before the operation completed. Typically because a parent context…
• fatal error: all goroutines are asleep - deadlock!All goroutines are blocked waiting on channels or locks with no goroutine able to make…
• fatal error: concurrent map writesMultiple goroutines are reading and writing to a map concurrently without synchronisation. Go…
• Go: build constraints exclude all Go files in ...Every file in the package was filtered out by build tags or by the filename suffix…
• go: cannot find main module; see 'go help modules'The command was run outside any module: there is no go.mod in the working directory or any…
• Go: checksum mismatch (SECURITY ERROR)The downloaded module's hash does not match go.sum or the public checksum database. This can…
• Go: declared and not usedGo treats an unused local variable as a compile error, not a warning, on the grounds that it…

See all 19 Go errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.