Go "unknown directive: toolchain" - Fix in CI

By Daniel Zoghalchali·Latchkey

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.

What this error means

A build fails with go.mod:4: unknown directive: toolchain. The workflow runs a pre-1.21 Go that does not understand the toolchain line.

go: errors parsing go.mod:
go.mod:4: unknown directive: toolchain

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.

# 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/*

Common causes

CI Go older than 1.21

The runner installed a pre-1.21 Go, which cannot parse the toolchain directive.

toolchain line added by a newer local Go

A newer local Go wrote a toolchain directive that the older CI toolchain rejects.

How to fix it

Upgrade the CI Go

1. Install Go 1.21 or newer so the toolchain directive parses.

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'

Track the version from go.mod

1. Drive setup-go from go.mod so CI never lags the directive.

- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod

How to prevent it

• Keep the CI Go at or above the version go.mod requires.
• Use go-version-file: go.mod to avoid drift.
• Bump CI when a newer local Go writes a toolchain line.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation