golang/go · error

go doc: %s: %v %s

Error message

go doc: %s: %v
%s

What it means

Generic wrapper returned by doc.runCmd when an exec.Command it launched (e.g. `go list -m`, `go env GOWORK`) fails. The message embeds the joined command line, the exec error, and the captured stderr so the underlying failure is visible. It is a propagation aid, not a distinct condition.

Source

Thrown at src/cmd/go/internal/doc/doc.go:316

				path, fragment, err := objectPath(userPath, pkg, symbol, method)
				if err != nil {
					return err
				}
				return doPkgsite(ctx, path, fragment)
			}
			return nil
		}
	}
}

func runCmd(env []string, cmdline ...string) (string, error) {
	var stdout, stderr strings.Builder
	cmd := exec.Command(cmdline[0], cmdline[1:]...)
	cmd.Env = env
	cmd.Stdout = &stdout
	cmd.Stderr = &stderr
	if err := cmd.Run(); err != nil {
		return "", fmt.Errorf("go doc: %s: %v\n%s\n", strings.Join(cmdline, " "), err, stderr.String())
	}
	return strings.TrimSpace(stdout.String()), nil
}

// returns a path followed by a fragment (or an error)
func objectPath(userPath string, pkg *Package, symbol, method string) (string, string, error) {
	var err error
	path := pkg.build.ImportPath
	if path == "." {
		// go/build couldn't determine the import path, probably
		// because this was a relative path into a module. Use
		// go list to get the import path.
		path, err = runCmd(nil, "go", "list", userPath)
		if err != nil {
			return "", "", err
		}
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Read the embedded stderr in the message to find the real cause.
2. Reproduce the inner command manually (it is printed) to iterate faster.
3. Fix the underlying go-list/go-env issue (module tidy, correct GOWORK).
4. Check `go version` matches the project.

Example fix

# the error already prints the failing command + stderr, e.g.:
#   go doc: go list -m: exit status 1: <stderr>
# reproduce and fix the inner command:
$ go list -m        # see the real error
$ go mod tidy

out, err := runCmd(env, "go", "list", "-m")
if err != nil {
    // err already contains the inner command + stderr; surface it verbatim
    log.Printf("doc helper failed: %v", err)
}

When it happens

Trigger: Any internal helper in go doc that shells out to `go` and the subprocess exits non-zero — module resolution failure, env error, go command crash. The wrapper fires in cmd.Run()'s err branch.

Common situations: Broken module state; go command itself misbehaving; env var (GOWORK/GOPATH) misconfiguration; the underlying go invocation hit one of its own errors.

Related errors

• unexpected stdout: %q
• can't resolve module using the vendor directory (Use -mod=m
• not a known dependency
• %v: %w
• cannot run go list: %v %s

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