go language version %s is not a toolchain version

Error message

go language version %s is not a toolchain version

What it means

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.

Source

Thrown at src/cmd/go/internal/modfetch/toolchain.go:118

	}

	// If we're asking about "go" (not "toolchain"), pretend to have
	// all earlier Go versions available without network access:
	// we will provide those ourselves, at least in GOTOOLCHAIN=auto mode.
	if r.path == "go" && gover.Compare(v, gover.Local()) <= 0 {
		return &RevInfo{Version: prefix + v}, nil
	}

	// Similarly, if we're asking about *exactly* the current toolchain,
	// we don't need to access the network to know that it exists.
	if r.path == "toolchain" && v == gover.Local() {
		return &RevInfo{Version: prefix + v}, nil
	}

	if gover.IsLang(v) {
		// We can only use a language (development) version if the current toolchain
		// implements that version, and the two checks above have ruled that out.
		return nil, fmt.Errorf("go language version %s is not a toolchain version", rev)
	}

	// Check that the underlying toolchain exists.
	// We always ask about linux-amd64 because that one
	// has always existed and is likely to always exist in the future.
	// This avoids different behavior validating go versions on different
	// architectures. The eventual download uses the right GOOS-GOARCH.
	info, err := r.repo.Stat(ctx, goToDL(v, "linux", "amd64"))
	if err != nil {
		return nil, err
	}

	// Return the info using the canonicalized rev
	// (toolchain 1.2 => toolchain go1.2).
	return &RevInfo{Version: prefix + v, Time: info.Time}, nil
}

func (r *toolchainRepo) Latest(ctx context.Context) (*RevInfo, error) {

View on GitHub (pinned to b6b368adc5)

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.

Example fix

# before
$ go get toolchain@1.21
# go language version 1.21 is not a toolchain version

# after: use full version
$ go get toolchain@go1.21.0
# or upgrade local Go to 1.21.x

Defensive patterns

Strategy: validation

Validate before calling

// Ensure toolchain versions include patch number
func validateToolchainVersion(rev string) error {
    v := strings.TrimPrefix(rev, "go")
    // Reject bare language versions like '1.21' without patch
    parts := strings.SplitN(v, ".", 3)
    if len(parts) < 3 {
        return fmt.Errorf("toolchain version %s lacks patch number (use e.g. 1.21.0)", rev)
    }
    return nil
}

Try / catch

if strings.Contains(stderr, "is not a toolchain version") {
    // User specified a language version (e.g., 1.21) for a toolchain query
    // Suggest: use 1.21.0 (full version) or upgrade local Go
}

Prevention

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)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/3e7334b0e81a9e1f. Report an issue: GitHub.