golang/go · warning

pattern %q does not specify a single package

Error message

pattern %q does not specify a single package

What it means

Returned by loadPackage when the supplied pattern is not a literal package path (search.NewMatch(pattern).IsLiteral() is false). go doc needs exactly one concrete package to render, so wildcards like ./..., std, or 'all' are rejected before any loading happens.

Source

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

		} else {
			nonInternal = append(nonInternal, m)
		}
	}
	if !deferInternal {
		return matches
	}
	if len(nonInternal) == 0 {
		return internal
	}
	// If the last non-internal match is returned, later retries should
	// not fall through to internal-only matches for the same package path.
	nonInternal[len(nonInternal)-1].nextOffset = dirs.offset
	return append(nonInternal, internal...)
}

func loadPackage(ctx context.Context, loader *modload.Loader, pattern string) (*load.Package, error) {
	if !search.NewMatch(pattern).IsLiteral() {
		return nil, fmt.Errorf("pattern %q does not specify a single package", pattern)
	}

	pkgOpts := load.PackageOpts{
		IgnoreImports:      true,
		SuppressBuildInfo:  true,
		SuppressEmbedFiles: true,
	}
	pkgs := load.PackagesAndErrors(loader, ctx, pkgOpts, []string{pattern})

	if len(pkgs) != 1 {
		return nil, fmt.Errorf("path %q matched multiple packages", pattern)
	}

	p := pkgs[0]
	if p.Error != nil {
		return nil, p.Error
	}
	return p, nil

View on GitHub (pinned to b6b368adc5)

Solutions

1. Pass a single literal import path or relative path (e.g. `go doc ./mypkg` or `go doc fmt`).
2. If you want to browse many packages, use pkgsite (`go doc -http`).
3. Expand the pattern externally and loop if you truly need many.

Example fix

# before
$ go doc ./...
# -> pattern "./..." does not specify a single package

# after
$ go doc ./mypkg
# or browse interactively
$ go doc -http

if !search.NewMatch(pattern).IsLiteral() {
    return fmt.Errorf("%q is a wildcard; pass a single literal package path", pattern)
}

func isLiteralPackage(p string) bool {
    return search.NewMatch(p).IsLiteral()
}

When it happens

Trigger: Running `go doc ./...`, `go doc std`, `go doc all`, or any pattern containing wildcards/meta-syntax accepted by the broader go list matcher.

Common situations: Habit of using ./... from build/test commands; passing package-list patterns to doc by mistake; copy-pasting a pattern from a go test invocation.

Related errors

• no such package: %s
• cannot combine -all and -short
• no symbol %s in package%s
• path %q matched multiple packages
• unexpected stdout: %q

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