Go "unknown directive: toolchain" - Fix in CI

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

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.

Related guides