Go "unknown directive" in go.mod in CI

By Daniel Zoghalchali·Latchkey

go.mod has a fixed set of directives (module, go, require, replace, exclude, retract, toolchain). An unrecognized keyword, or a newer directive on an older Go, is rejected as "unknown directive".

What this error means

A go command fails parsing go.mod with "go.mod:5: unknown directive: toolchain" (or another keyword), usually on an older runner Go.

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

Common causes

A newer directive on an older toolchain

The toolchain directive was introduced in Go 1.21; a Go 1.20 runner does not recognize it and reports an unknown directive.

A typo in a directive keyword

A misspelled keyword (for example requires instead of require) is not a known directive.

How to fix it

Upgrade the runner Go to understand the directive

1. Pin setup-go to a version that supports the directive (1.21+ for toolchain).
2. Re-run the build.
3. Keep the CI Go aligned with the directives your go.mod uses.

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

Fix or remove an unrecognized line

Correct a misspelled keyword, or remove a directive your supported Go versions do not understand.

How to prevent it

• Match the CI Go version to the directives in go.mod.
• Edit go.mod with go commands so keywords stay valid.
• Run a version matrix to catch directive incompatibilities.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation