golang/go · error

incorrect number of packages: want 1, got %d

Error message

incorrect number of packages: want 1, got %d

What it means

Returned by loadVersioned when PackagesAndErrorsOutsideModule for a single `pkgPath@version` argument does not yield exactly one package. The versioned-doc lookup assumes one package per (path, version); zero means the version/path is absent, two-plus means the spec resolved ambiguously.

Source

Thrown at src/cmd/go/internal/doc/mod.go:28

	"fmt"
	"os/exec"

	"cmd/go/internal/load"
	"cmd/go/internal/modload"
)

// loadVersioned loads a package at a specific version.
func loadVersioned(ctx context.Context, loader *modload.Loader, pkgPath, version string) (*load.Package, error) {
	var opts load.PackageOpts
	args := []string{
		fmt.Sprintf("%s@%s", pkgPath, version),
	}
	pkgs, err := load.PackagesAndErrorsOutsideModule(loader, ctx, opts, args)
	if err != nil {
		return nil, err
	}
	if len(pkgs) != 1 {
		return nil, fmt.Errorf("incorrect number of packages: want 1, got %d", len(pkgs))
	}
	return pkgs[0], nil
}

// inferVersion checks if the argument matches a command on $PATH and returns its module path and version.
func inferVersion(arg string) (pkgPath, version string, ok bool) {
	path, err := exec.LookPath(arg)
	if err != nil {
		return "", "", false
	}
	bi, err := buildinfo.ReadFile(path)
	if err != nil {
		return "", "", false
	}
	if bi.Main.Path == "" || bi.Main.Version == "" {
		return "", "", false
	}
	// bi.Path is the package path for the main package.

View on GitHub (pinned to b6b368adc5)

Solutions

1. Verify the version exists: `go list -m -versions <module>`.
2. Make sure you pass a package path, not just the module root path.
3. Use a fully-qualified semantic version (e.g. @v1.2.0, not @v1.2).
4. Check for replace directives that alter resolution.

Example fix

# before
$ go doc example.com/lib@v1.2
# -> incorrect number of packages: want 1, got 0

# after
$ go list -m -versions example.com/lib   # find a real tag
$ go doc example.com/lib@v1.2.0

// verify the version exists before the versioned doc call
if out, err := exec.Command("go", "list", "-m", "-versions", modPath).Output(); err != nil || !bytes.Contains(out, []byte(version)) {
    return fmt.Errorf("version %s not available for %s", version, modPath)
}

func looksLikeVersionedSpec(s string) bool {
    return goVersionRegexp.MatchString(s) // e.g. pkg@v1.2.3
}

When it happens

Trigger: Running `go doc <pkg>@<version>` where the version does not exist, the module path is wrong, or the spec resolves to multiple packages (e.g. a meta-package or build-tag split).

Common situations: Typo in version tag (@v1.2 instead of @v1.2.0); pointing at a module path rather than a package path; version replaced/retired; ambiguous main/meta packages.

Related errors

• module requires Go ${p.Module.GoVersion} or later
• unexpected stdout: %q
• must have SWIG version >= 3.0.6
• tls: client offered TLS version older than TLS 1.3
• cannot combine -all and -short

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