golang/go · error

built pkgsite binary does not exist: %w

Error message

built pkgsite binary does not exist: %w

What it means

Thrown only on the test path of doPkgsite (when TEST_GODOC_BUILD_ONLY is set): after buildPkgsite(ctx) runs, os.Stat(pkgsite) is checked and the error wraps the failing stat. It signals that the pkgsite helper binary was not produced where the build claimed it would be. End users of `go doc` never see it; it exists so the test harness can fail fast when the bundled pkgsite build is broken.

Source

Thrown at src/cmd/go/internal/doc/pkgsite.go:148

	fields := strings.Fields(vars)
	if err == nil && len(fields) == 2 {
		goproxy, gomodcache := fields[0], fields[1]
		gomodcache = filepath.Join(gomodcache, "cache", "download")
		// Convert absolute path to file URL. pkgsite will not accept
		// Windows absolute paths because they look like a host:path remote.
		// TODO(golang.org/issue/32456): use url.FromFilePath when implemented.
		if strings.HasPrefix(gomodcache, "/") {
			gomodcache = "file://" + gomodcache
		} else {
			gomodcache = "file:///" + filepath.ToSlash(gomodcache)
		}
		env = append(env, "GOPROXY="+gomodcache+","+goproxy)
	}

	pkgsite := buildPkgsite(ctx)
	if os.Getenv("TEST_GODOC_BUILD_ONLY") != "" {
		if _, err := os.Stat(pkgsite); err != nil {
			return fmt.Errorf("built pkgsite binary does not exist: %w", err)
		}
		return nil
	}
	cmd := exec.Command(pkgsite, "-gorepo", cfg.GOROOT, "-http", addr, "-open", path)
	cmd.Env = env
	cmd.Stdout = os.Stderr
	cmd.Stderr = os.Stderr

	if err := cmd.Run(); err != nil {
		if ee, ok := errors.AsType[*exec.ExitError](err); ok {
			// Exit with the same exit status as pkgsite to avoid
			// printing of "exit status" error messages.
			// Any relevant messages have already been printed
			// to stdout or stderr.
			os.Exit(ee.ExitCode())
		}
		return err
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Inspect the underlying wrapped error (%w) from os.Stat — it tells you whether the path is missing, a permission issue, or a stale symlink.
2. Confirm buildPkgsite actually wrote the binary to the returned path; run the build step standalone and `ls -l` the result.
3. Re-run `go build`/`go install` for the pkgsite target with the same GOOS/GOARCH the test uses, so the output path matches.
4. If you are mocking buildPkgsite in a test, make the stub write an empty file at the returned path before returning.

Example fix

// before (test stub that returns a path but never writes it)
func buildPkgsite(ctx context.Context) string { return "/tmp/pkgsite" }
// after
func buildPkgsite(ctx context.Context) string {
    p := filepath.Join(os.TempDir(), "pkgsite")
    if _, err := os.Stat(p); err != nil {
        if err := os.WriteFile(p, []byte("#!/bin/sh\n"), 0755); err != nil { panic(err) }
    }
    return p
}

// Before relying on the pkgsite path returned by buildPkgsite,
// verify it actually exists on disk.
if _, err := os.Stat(pkgsitePath); err != nil {
    return fmt.Errorf("pkgsite not built yet: %w", err)
}

When it happens

Trigger: Running the cmd/go godoc test with TEST_GODOC_BUILD_ONLY=1 in the environment and buildPkgsite returning a path whose file does not yet exist on disk (build was skipped, failed silently, or wrote elsewhere).

Common situations: A broken/short-circuited buildPkgsite in a dev toolchain; cross-compile setups where the built binary lands in a different GOBIN/GOPATH/bin; stale test shims that mock the build without writing the file; partial builds interrupted before the pkgsite target completes.

Related errors

• import cycle not allowed in test
• multiple definitions of TestMain
• multiple //go:build comments
• import cycle not allowed
• use of vendored package not allowed

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