{"record":{"id":"4f7910f8c7a9b867","repo":"golang/go","slug":"switching-to-go-v-w","errorCode":null,"errorMessage":"switching to go >= %v: %w","messagePattern":"switching to go >= (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cmd/go/internal/toolchain/switch.go","lineNumber":105,"sourceCode":"//\n// Otherwise, Switch prints an informational message giving a reason for the\n// switch and the toolchain being invoked and then switches toolchains.\n// This operation never returns.\nfunc (s *Switcher) Switch(ctx context.Context) {\n\tif !s.NeedSwitch() {\n\t\tfor _, err := range s.Errors {\n\t\t\tbase.Error(err)\n\t\t}\n\t\treturn\n\t}\n\n\t// Switch to newer Go toolchain if necessary and possible.\n\ttv, err := NewerToolchain(ctx, s.ld.Fetcher(), s.TooNew.GoVersion)\n\tif err != nil {\n\t\tfor _, err := range s.Errors {\n\t\t\tbase.Error(err)\n\t\t}\n\t\tbase.Error(fmt.Errorf(\"switching to go >= %v: %w\", s.TooNew.GoVersion, err))\n\t\treturn\n\t}\n\n\tfmt.Fprintf(os.Stderr, \"go: %v requires go >= %v; switching to %v\\n\", s.TooNew.What, s.TooNew.GoVersion, tv)\n\tcounterSwitchExec.Inc()\n\tExec(s.ld, tv)\n\tpanic(\"unreachable\")\n}\n\nvar counterSwitchExec = counter.New(\"go/toolchain/switch-exec\")\n\n// SwitchOrFatal attempts a toolchain switch based on the information in err\n// and otherwise falls back to base.Fatal(err).\nfunc SwitchOrFatal(ld *modload.Loader, ctx context.Context, err error) {\n\ts := NewSwitcher(ld)\n\ts.Error(err)\n\ts.Switch(ctx)\n\tbase.Exit()","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/golang/go/blob/b6b368adc57c96c3151d224d172029f233ead2c3/src/cmd/go/internal/toolchain/switch.go#L87-L123","documentation":"When a module's go directive requires a newer Go version than the running toolchain, the Switcher attempts an automatic toolchain download/switch (if GOTOOLCHAIN permits). If the underlying NewerToolchain call fails — typically due to network, proxy, or cache issues — the failure is wrapped with the required version for context.","triggerScenarios":"GOTOOLCHAIN=auto (or *+auto), a dependency declares `go 1.X` newer than your installed Go, and NewerToolchain returns an error (network failure, GOPROXY=off with empty cache, disk full in module cache).","commonSituations":"Offline or air-gapped development; corporate proxy blocking proxy.golang.org; GOPROXY misconfigured; full disk in GOPATH/pkg/mod cache; a CI runner with GOTOOLCHAIN=auto but no network.","solutions":["Check network connectivity to your GOPROXY (default proxy.golang.org)","Install the required Go version manually and set GOTOOLCHAIN=local to skip auto-switching","Pre-download the toolchain: `go mod download` with network available, or `go install golang.org/dl/go1.X@latest`","Verify GOPROXY is not set to off or a broken URL: `go env GOPROXY`"],"exampleFix":"# before: GOTOOLCHAIN=auto fails offline\nexport GOTOOLCHAIN=auto\ngo build ./...\n\n# after: pin to locally installed toolchain\nexport GOTOOLCHAIN=local\ngo build ./...\n\n# or install the needed version first\nexport GOTOOLCHAIN=go1.23.0\ngo build ./...","handlingStrategy":"fallback","validationCode":"# Check if the required toolchain is available before building\nREQUIRED_GO=$(go list -f '{{.Module.GoVersion}}' -m 2>/dev/null || true)\nif [ -n \"$REQUIRED_GO\" ]; then\n  INSTALLED=$(go version | grep -oP 'go\\K[0-9]+\\.[0-9]+(\\.[0-9]+)?')\n  if ! go version | grep -q \"$REQUIRED_GO\"; then\n    export GOTOOLCHAIN=local  # use installed version instead of auto-switching\n  fi\nfi","typeGuard":null,"tryCatchPattern":"# Retry with fallback to local toolchain on switch failure\nif ! go build ./... 2>/dev/null; then\n  echo 'Toolchain switch failed — retrying with GOTOOLCHAIN=local'\n  GOTOOLCHAIN=local go build ./...\nfi","preventionTips":["Pin GOTOOLCHAIN=local in CI if you control the Go version on the runner","Pre-install required Go versions on build machines","Verify GOPROXY is reachable before relying on auto toolchain switching"],"tags":["toolchain","version-management","network","gotoolchain"],"backgroundTag":null,"analyzedSha":"b6b368adc57c96c3151d224d172029f233ead2c3","analyzedAt":"2026-08-12T00:22:02.250Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}