golang/go · error

default=%s too new (toolchain is go%s)

Error message

default=%s too new (toolchain is go%s)

What it means

Thrown by CheckGodebug when the 'default' GODEBUG key specifies a Go version newer than the running toolchain. After validating the value is a proper goVERSION, it calls gover.Compare against gover.Local() (the toolchain's own version). If the requested default exceeds the toolchain version, the setting is rejected because the toolchain cannot provide defaults for a future Go version.

Source

Thrown at src/cmd/go/internal/modload/init.go:2300

func CheckGodebug(verb, k, v string) error {
	if strings.ContainsAny(k, " \t") {
		return fmt.Errorf("key contains space")
	}
	if strings.ContainsAny(v, " \t") {
		return fmt.Errorf("value contains space")
	}
	if strings.ContainsAny(k, ",") {
		return fmt.Errorf("key contains comma")
	}
	if strings.ContainsAny(v, ",") {
		return fmt.Errorf("value contains comma")
	}
	if k == "default" {
		if !strings.HasPrefix(v, "go") || !gover.IsValid(v[len("go"):]) {
			return fmt.Errorf("value for default= must be goVERSION")
		}
		if gover.Compare(v[len("go"):], gover.Local()) > 0 {
			return fmt.Errorf("default=%s too new (toolchain is go%s)", v, gover.Local())
		}
		return nil
	}
	if godebugs.Lookup(k) != nil {
		return nil
	}
	for _, info := range godebugs.Removed {
		if info.Name == k {
			if info.Old(v) {
				return fmt.Errorf("removed GODEBUG %q set to old value %q (https://go.dev/doc/godebug#go-1%v)", k, v, info.Removed)
			}
			// Using a removed GODEBUG setting with a non-old value is ok (see go.dev/issue/76163).
			return nil
		}
	}
	return fmt.Errorf("unknown %s %q", verb, k)
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Install or switch to a Go toolchain at or above the version specified in the default= value (use 'go env GOTOOLCHAIN' and the toolchain directive).
2. Alternatively, lower the default= value in go.mod/go.work to match or be below your current toolchain version.
3. Ensure GOTOOLCHAIN=auto is set so Go can auto-download the required toolchain.

Example fix

// before (toolchain is go1.22)
godebug default=go1.23

// after — let GOTOOLCHAIN=auto fetch go1.23, or downgrade:
godebug default=go1.22

// Check default= is not newer than the local toolchain before writing.
func checkDefaultNotTooNew(v string) error {
    if !strings.HasPrefix(v, "go") {
        return fmt.Errorf("value for default= must be goVERSION")
    }
    if gover.Compare(v[len("go"):], gover.Local()) > 0 {
        return fmt.Errorf("default=%s too new (toolchain is go%s)", v, gover.Local())
    }
    return nil
}

When it happens

Trigger: godebug directive 'default=go1.25' is set but the active toolchain is go1.23. gover.Compare("1.25", "1.23") returns > 0, triggering the error. Common when a go.mod targets a newer Go version than the installed toolchain without the toolchain directive auto-downloading a newer toolchain.

Common situations: Cloning a project that targets a newer Go version than what is installed. Setting the default GODEBUG manually to match a go.mod 'go' directive that is ahead of the local toolchain. Using an older Go installation.

Related errors

• value for default= must be goVERSION
• key contains space
• value contains space
• key contains comma
• value contains comma

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