What causes "must specify exactly one package" in vitessio/vitess?

Run codegen from the repository root with the default/expected package pattern

must specify exactly one package

Error message

must specify exactly one package

What it means

This error comes from the codegen helper in vtctldclient that loads a Go package pattern via golang.org/x/tools/go/packages. It enforces that exactly one package matches the given pattern; zero or multiple matching packages make code generation ambiguous, so loadPackage fails.

Source

Thrown at go/vt/vtctl/vtctldclient/codegen/main.go:302

func addImport(localImport string, pkgPath string, importNames []string, imports map[string]string) []string {
	if _, ok := imports[localImport]; !ok {
		importNames = append(importNames, localImport)
	}

	imports[localImport] = pkgPath
	return importNames
}

func loadPackage(source string) (*packages.Package, error) {
	pkgs, err := packages.Load(&packages.Config{
		Mode: packages.NeedTypes | packages.NeedSyntax | packages.NeedTypesInfo,
	}, source)
	if err != nil {
		return nil, err
	}

	if len(pkgs) != 1 {
		return nil, errors.New("must specify exactly one package")
	}

	pkg := pkgs[0]
	if len(pkg.Errors) > 0 {
		var err error

		for _, e := range pkg.Errors {
			switch err {
			case nil:
				err = fmt.Errorf("errors loading package %s: %s", source, e.Error())
			default:
				err = fmt.Errorf("%w; %s", err, e.Error())
			}
		}

		return nil, err
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

Run codegen from the repository root with the default/expected package pattern
Verify the package path passed to loadPackage exists and names exactly one package
Ensure the target directory contains a single package (no mixed package names, exclude _test packages from the pattern)

Example fix

// before
go run ./go/vt/vtctl/vtctldclient/codegen ./go/vt/proto/...
// after
go run ./go/vt/vtctl/vtctldclient/codegen ./go/vt/proto/vtctlservicepb

Defensive patterns

Strategy: validation

Validate before calling

cfg := &packages.Config{Mode: packages.NeedName | packages.NeedFiles}
pkgs, err := packages.Load(cfg, pattern)
if err != nil { return err }
if len(pkgs) != 1 {
    return fmt.Errorf("pattern %q matched %d packages, need exactly 1", pattern, len(pkgs))
}

Type guard

func exactlyOnePackage(pkgs []*packages.Package) bool { return len(pkgs) == 1 }

Try / catch

if _, err := loadPackage(pattern); err != nil {
    if strings.Contains(err.Error(), "must specify exactly one package") {
        return fmt.Errorf("codegen input error: %w", err)
    }
    return err
}

Prevention

Run codegen from the repo root with the exact documented package path
Avoid wildcard patterns like ./... in codegen inputs
Check target directories contain a single package name

When it happens

Trigger: Running the vtctldclient codegen (go run ./go/vt/vtctl/vtctldclient/codegen) with a package pattern that matches zero packages (wrong path/typo) or more than one package (a directory containing multiple packages, or a broad pattern like ./...).

Common situations: Regenerating the vtctldclient command stubs after moving/renaming proto service files; running codegen from the wrong working directory; a directory containing both package foo and foo_test packages.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/19795e81cbdbc271. Report an issue: GitHub.