What causes "%s: %w" in golang/go?

Verify the exact module path and version tag exist (check the registry/VCS).

%s: %w

Error message

%s: %w

What it means

Wraps any error from `modload.QueryPackages` when resolving the first `package@version` argument against the module proxy or VCS. This is the primary module-resolution step; failures include module-not-found, version-not-found, network errors, and checksum/sumdb mismatches. The original argument is prefixed so the user sees which input failed.

Source

Thrown at src/cmd/go/internal/load/pkg.go:3436

	patterns = search.CleanPatterns(patterns)

	// Query the module providing the first argument, load its go.mod file, and
	// check that it doesn't contain directives that would cause it to be
	// interpreted differently if it were the main module.
	//
	// If multiple modules match the first argument, accept the longest match
	// (first result). It's possible this module won't provide packages named by
	// later arguments, and other modules would. Let's not try to be too
	// magical though.
	allowed := ld.CheckAllowed
	if modload.IsRevisionQuery(firstPath, version) {
		// Don't check for retractions if a specific revision is requested.
		allowed = nil
	}
	noneSelected := func(path string) (version string) { return "none" }
	qrs, err := modload.QueryPackages(ld, ctx, patterns[0], version, noneSelected, allowed)
	if err != nil {
		return nil, fmt.Errorf("%s: %w", args[0], err)
	}
	rootMod := qrs[0].Mod
	deprecation, err := modload.CheckDeprecation(ld, ctx, rootMod)
	if err != nil {
		return nil, fmt.Errorf("%s: %w", args[0], err)
	}
	if deprecation != "" {
		fmt.Fprintf(os.Stderr, "go: module %s is deprecated: %s\n", rootMod.Path, modload.ShortMessage(deprecation, ""))
	}
	data, err := ld.Fetcher().GoMod(ctx, rootMod.Path, rootMod.Version)
	if err != nil {
		return nil, fmt.Errorf("%s: %w", args[0], err)
	}
	f, err := modfile.Parse("go.mod", data, nil)
	if err != nil {
		return nil, fmt.Errorf("%s (in %s): %w", args[0], rootMod, err)
	}
	directiveFmt := "%s (in %s):\n" +

View on GitHub (pinned to b6b368adc5)

Solutions

Verify the exact module path and version tag exist (check the registry/VCS).
Inspect proxy/network config: `go env GOPROXY GOSUMDB GOPRIVATE` and set `GOPRIVATE` for private modules.
Reproduce the underlying error with `go mod download <module>@<version>` for a clearer message.
Retry after `go clean -modcache` if the cache appears corrupt.

Defensive patterns

Strategy: retry

Validate before calling

// Validate reachability before the real command.
func checkModuleResolvable(mod, ver string) error {
    cmd := exec.Command("go", "mod", "download", mod+"@"+ver)
    return cmd.Run()
}

Try / catch

// Retry transient proxy/network failures with backoff.
var lastErr error
for i := 0; i < 3; i++ {
    err := runGoInstall(modAtVersion)
    if err == nil { return nil }
    lastErr = err
    if !isTransientProxyErr(err) { break }
    time.Sleep(time.Duration(1<<i) * time.Second)
}
return lastErr

Prevention

Set GOPRIVATE for private modules so they bypass the public proxy.
Verify the module path/version against the VCS or registry before scripting installs.
Run `go mod download pkg@ver` first to surface the underlying proxy error.

When it happens

Trigger: `go install example.com/nonexistent@v1.0.0`; offline network; `GOPROXY=off`; `GOPRIVATE` misconfigured so a private module is queried against the public proxy and rejected; a tag that does not exist.

Common situations: Typo in module path or version, network/proxy outage, air-gapped environment, private repo auth not configured, sumdb verification failure for a private module.

Related errors

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