# Go "unknown directive: toolchain" - Fix in CI

> Fix Go "unknown directive: toolchain" in CI - go.mod has a toolchain line an older Go cannot parse. Upgrade Go to 1.21+ in the workflow.

Source: https://latchkey.dev/learn/go/go-toolchain-unknown-directive-old-go-in-ci  
Updated: 2026-06-26

The toolchain directive in go.mod was introduced in Go 1.21. An older toolchain cannot parse it and rejects go.mod entirely, so the build fails before compiling.

## Diagnose it: module path, proxy, or checksum?

Go module errors name the module but rarely the layer that failed. Separate the three: the module path does not resolve, the proxy cannot serve it, or the checksum database disagrees with what was downloaded.

```Terminal
# what Go resolves and from where
go env GOPROXY GOSUMDB GOPRIVATE GOFLAGS

# does the module resolve at all, bypassing the build?
go list -m -versions github.com/org/module

# verify the module cache against go.sum
go mod verify

# private modules must be excluded from proxy and sumdb
go env -w GOPRIVATE=github.com/yourorg/*
```

> A private module fetched through the public proxy fails with a confusing 410 or checksum mismatch rather than an auth error. Setting `GOPRIVATE` for your org prefix removes an entire class of CI-only module failures.

## FAQ

### What causes Go "unknown directive: toolchain"?

There are 2 common causes: ci go older than 1.21 and toolchain line added by a newer local go. The runner installed a pre-1.21 Go, which cannot parse the toolchain directive.

### How do I fix Go "unknown directive: toolchain"?

There are 2 fixes depending on which cause you have: upgrade the ci go and track the version from go.mod. Work through them in order, since the first is the most common.

### What does Go "unknown directive: toolchain" actually mean?

A build fails with go.mod:4: unknown directive: toolchain.

### How do I stop Go "unknown directive: toolchain" happening again?

Keep the CI Go at or above the version go.mod requires. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt