{"record":{"id":"9bf3a66480955766","repo":"golang/go","slug":"module-requires-go-p-module-goversion-or-later","errorCode":null,"errorMessage":"module requires Go ${p.Module.GoVersion} or later","messagePattern":"module requires Go (.+?) or later","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/work/exec.go","lineNumber":653,"sourceCode":"\tif need == 0 {\n\t\treturn nil\n\t}\n\tdefer b.flushOutput(a)\n\n\tdefer func() {\n\t\tif err != nil && b.IsCmdList && b.NeedError && p.Error == nil {\n\t\t\tp.Error = &load.PackageError{Err: err}\n\t\t}\n\t}()\n\n\tif p.Error != nil {\n\t\t// Don't try to build anything for packages with errors. There may be a\n\t\t// problem with the inputs that makes the package unsafe to build.\n\t\treturn p.Error\n\t}\n\n\tif p.Module != nil && !allowedVersion(p.Module.GoVersion) {\n\t\treturn errors.New(\"module requires Go \" + p.Module.GoVersion + \" or later\")\n\t}\n\n\tif err := b.checkDirectives(a); err != nil {\n\t\treturn err\n\t}\n\n\tif err := sh.Mkdir(a.Objdir); err != nil {\n\t\treturn err\n\t}\n\n\t// Load cached vet config, but only if that's all we have left\n\t// (need == needVet, not testing just the one bit).\n\t// If we are going to do a full build anyway,\n\t// we're going to regenerate the files in the build action anyway.\n\tif need == needVet {\n\t\tif err := b.loadCachedVet(a, a.Deps); err == nil {\n\t\t\tneed &^= needVet\n\t\t}","sourceCodeStart":635,"sourceCodeEnd":671,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/work/exec.go#L635-L671","documentation":"Thrown by (*Builder).build in cmd/go/internal/work when the module being compiled declares a `go` directive (e.g. `go 1.23`) newer than the running go toolchain's own version (checked via allowedVersion). This is the toolchain's guard against using language features the binary cannot compile — the go directive is treated as a minimum-required-toolchain contract since Go 1.21.","triggerScenarios":"Building a module whose go.mod has e.g. `go 1.23` with an installed go 1.21 toolchain. Pulling a dependency that bumped its go directive. Running an older system go against a freshly generated module (`go mod init` on a newer toolchain, then building on an older one).","commonSituations":"CI images pinned to an older Go. Local developers on distro-provided Go (often older) building modern modules. A transitive dependency raising its minimum. `GOTOOLCHAIN=local` set explicitly, which disables the automatic toolchain download that would otherwise transparently fix this.","solutions":["Upgrade your installed Go to at least the version named in the failing module's go.mod.","Allow automatic toolchain switching: unset GOTOOLCHAIN or set GOTOOLCHAIN=auto (default) so go fetches the required version.","Pin the toolchain in your own go.mod via a `toolchain go1.23.0` line so all contributors and CI use the same version.","As a last resort, lower the go directive in go.mod — but only if the code genuinely does not use newer language features, and prefer upgrading instead."],"exampleFix":"# before: go.mod says `go 1.23` but installed go is 1.21\n$ go version\ngo version go1.21.0\n$ go build ./...\n# -> module requires Go 1.23 or later\n\n# after: enable auto toolchain download\n$ unset GOTOOLCHAIN\n$ go build ./...   # go downloads go1.23 and re-runs","handlingStrategy":"validation","validationCode":"func checkGoVersion(required, installed string) error {\n    r := strings.Split(required, \".\"); i := strings.Split(installed, \".\")\n    if len(r) >= 2 && len(i) >= 2 {\n        if r[0] > i[0] || (r[0] == i[0] && r[1] > i[1]) {\n            return fmt.Errorf(\"module needs go%s; you have go%s — upgrade or set GOTOOLCHAIN=auto\", required, installed)\n        }\n    }\n    return nil\n}","typeGuard":"func toolchainSatisfies(required, installed string) bool {\n    return checkGoVersion(required, installed) == nil\n}","tryCatchPattern":null,"preventionTips":["Pin the toolchain in go.mod via a `toolchain` directive so all contributors match.","Leave GOTOOLCHAIN at its default (auto) so go can fetch the required version.","Upgrade CI Go images promptly when the project's go directive bumps."],"tags":["go-toolchain","version","module","go-directive","toolchain"],"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:17:08.281Z"}