golang/go · error

switching to go >= %v: %w

Error message

switching to go >= %v: %w

What it means

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.

Source

Thrown at src/cmd/go/internal/toolchain/switch.go:105

//
// Otherwise, Switch prints an informational message giving a reason for the
// switch and the toolchain being invoked and then switches toolchains.
// This operation never returns.
func (s *Switcher) Switch(ctx context.Context) {
	if !s.NeedSwitch() {
		for _, err := range s.Errors {
			base.Error(err)
		}
		return
	}

	// Switch to newer Go toolchain if necessary and possible.
	tv, err := NewerToolchain(ctx, s.ld.Fetcher(), s.TooNew.GoVersion)
	if err != nil {
		for _, err := range s.Errors {
			base.Error(err)
		}
		base.Error(fmt.Errorf("switching to go >= %v: %w", s.TooNew.GoVersion, err))
		return
	}

	fmt.Fprintf(os.Stderr, "go: %v requires go >= %v; switching to %v\n", s.TooNew.What, s.TooNew.GoVersion, tv)
	counterSwitchExec.Inc()
	Exec(s.ld, tv)
	panic("unreachable")
}

var counterSwitchExec = counter.New("go/toolchain/switch-exec")

// SwitchOrFatal attempts a toolchain switch based on the information in err
// and otherwise falls back to base.Fatal(err).
func SwitchOrFatal(ld *modload.Loader, ctx context.Context, err error) {
	s := NewSwitcher(ld)
	s.Error(err)
	s.Switch(ctx)
	base.Exit()

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check network connectivity to your GOPROXY (default proxy.golang.org)
2. Install the required Go version manually and set GOTOOLCHAIN=local to skip auto-switching
3. Pre-download the toolchain: `go mod download` with network available, or `go install golang.org/dl/go1.X@latest`
4. Verify GOPROXY is not set to off or a broken URL: `go env GOPROXY`

Example fix

# before: GOTOOLCHAIN=auto fails offline
export GOTOOLCHAIN=auto
go build ./...

# after: pin to locally installed toolchain
export GOTOOLCHAIN=local
go build ./...

# or install the needed version first
export GOTOOLCHAIN=go1.23.0
go build ./...

# Check if the required toolchain is available before building
REQUIRED_GO=$(go list -f '{{.Module.GoVersion}}' -m 2>/dev/null || true)
if [ -n "$REQUIRED_GO" ]; then
  INSTALLED=$(go version | grep -oP 'go\K[0-9]+\.[0-9]+(\.[0-9]+)?')
  if ! go version | grep -q "$REQUIRED_GO"; then
    export GOTOOLCHAIN=local  # use installed version instead of auto-switching
  fi
fi

# Retry with fallback to local toolchain on switch failure
if ! go build ./... 2>/dev/null; then
  echo 'Toolchain switch failed — retrying with GOTOOLCHAIN=local'
  GOTOOLCHAIN=local go build ./...
fi

When it happens

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

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

Related errors

• no releases found for go >= %v
• failed to locate cmd/go for target platform
• failed to locate cmd/compile for target platform
• GOROOT not found
• ${GoModToolVersion} is required for tool directives in go.mo

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