{"record":{"id":"3e7334b0e81a9e1f","repo":"golang/go","slug":"go-language-version-s-is-not-a-toolchain-version","errorCode":null,"errorMessage":"go language version %s is not a toolchain version","messagePattern":"go language version (.+?) is not a toolchain version","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/modfetch/toolchain.go","lineNumber":118,"sourceCode":"\t}\n\n\t// If we're asking about \"go\" (not \"toolchain\"), pretend to have\n\t// all earlier Go versions available without network access:\n\t// we will provide those ourselves, at least in GOTOOLCHAIN=auto mode.\n\tif r.path == \"go\" && gover.Compare(v, gover.Local()) <= 0 {\n\t\treturn &RevInfo{Version: prefix + v}, nil\n\t}\n\n\t// Similarly, if we're asking about *exactly* the current toolchain,\n\t// we don't need to access the network to know that it exists.\n\tif r.path == \"toolchain\" && v == gover.Local() {\n\t\treturn &RevInfo{Version: prefix + v}, nil\n\t}\n\n\tif gover.IsLang(v) {\n\t\t// We can only use a language (development) version if the current toolchain\n\t\t// implements that version, and the two checks above have ruled that out.\n\t\treturn nil, fmt.Errorf(\"go language version %s is not a toolchain version\", rev)\n\t}\n\n\t// Check that the underlying toolchain exists.\n\t// We always ask about linux-amd64 because that one\n\t// has always existed and is likely to always exist in the future.\n\t// This avoids different behavior validating go versions on different\n\t// architectures. The eventual download uses the right GOOS-GOARCH.\n\tinfo, err := r.repo.Stat(ctx, goToDL(v, \"linux\", \"amd64\"))\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Return the info using the canonicalized rev\n\t// (toolchain 1.2 => toolchain go1.2).\n\treturn &RevInfo{Version: prefix + v, Time: info.Time}, nil\n}\n\nfunc (r *toolchainRepo) Latest(ctx context.Context) (*RevInfo, error) {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/modfetch/toolchain.go#L100-L136","documentation":"This error occurs when a 'toolchain' module query uses a Go language version (e.g., '1.21' without a patch number) that the currently running toolchain does not implement. The code first checks if the version equals the local toolchain version; if not, it checks gover.IsLang — true for versions like '1.21' that have no patch/prerelease. Since the current toolchain doesn't match this language version (checked above), the language version can't resolve to an installable toolchain.","triggerScenarios":"Querying 'toolchain@1.21' (a bare language version) when the current Go toolchain is not 1.21.x. The IsLang check passes (it's a language version like '1.21'), but the earlier checks (r.path == 'toolchain' && v == gover.Local()) already failed, meaning this language version is not the current toolchain's version.","commonSituations":"A go.mod has a 'go 1.21' directive (language version) and GOTOOLCHAIN=auto tries to find a toolchain matching it, but the installed Go is older. A developer on Go 1.20 tries 'go get toolchain@1.22' (language version, no patch). The toolchain auto-switch logic encounters a language version that doesn't match the running toolchain.","solutions":["Specify a full toolchain version with patch number: use 'toolchain@go1.21.0' instead of 'toolchain@1.21'.","Upgrade the local Go toolchain to match the desired language version: install Go 1.21.x if you need '1.21' support.","Set GOTOOLCHAIN=auto to let Go download the appropriate toolchain automatically when it encounters a newer 'go' directive.","Update the 'go' directive in go.mod to a version your toolchain supports."],"exampleFix":"# before\n$ go get toolchain@1.21\n# go language version 1.21 is not a toolchain version\n\n# after: use full version\n$ go get toolchain@go1.21.0\n# or upgrade local Go to 1.21.x","handlingStrategy":"validation","validationCode":"// Ensure toolchain versions include patch number\nfunc validateToolchainVersion(rev string) error {\n    v := strings.TrimPrefix(rev, \"go\")\n    // Reject bare language versions like '1.21' without patch\n    parts := strings.SplitN(v, \".\", 3)\n    if len(parts) < 3 {\n        return fmt.Errorf(\"toolchain version %s lacks patch number (use e.g. 1.21.0)\", rev)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if strings.Contains(stderr, \"is not a toolchain version\") {\n    // User specified a language version (e.g., 1.21) for a toolchain query\n    // Suggest: use 1.21.0 (full version) or upgrade local Go\n}","preventionTips":["Always specify full versions (1.21.0) for toolchain queries, not language versions (1.21)","Keep the local Go toolchain updated to match project go.mod requirements","Use GOTOOLCHAIN=auto to let Go handle toolchain selection automatically","Understand the difference: 'go 1.21' (language version in go.mod) vs 'toolchain go1.21.0' (full toolchain version)"],"tags":["go-toolchain","go-version","gotoolchain","validation"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}