golang/go · error

invalid pkg-config package name: %s

Error message

invalid pkg-config package name: %s

What it means

Before invoking pkg-config, the go command validates each package-name argument with load.SafeArg, which rejects names whose first byte is not alphanumeric, '.', '_', '/', or a multibyte rune. If a name fails, the build aborts before pkg-config runs. This stops malformed or hostile package names (e.g. those starting with '-', '$', '*', '~', '(') from being passed to the shell or pkg-config.

Source

Thrown at src/cmd/go/internal/work/exec.go:2072

func (b *Builder) getPkgConfigFlags(a *Action, p *load.Package) (cflags, ldflags []string, err error) {
	sh := b.Shell(a)
	if pcargs := p.CgoPkgConfig; len(pcargs) > 0 {
		// pkg-config permits arguments to appear anywhere in
		// the command line. Move them all to the front, before --.
		var pcflags []string
		var pkgs []string
		for _, pcarg := range pcargs {
			if pcarg == "--" {
				// We're going to add our own "--" argument.
			} else if strings.HasPrefix(pcarg, "--") {
				pcflags = append(pcflags, pcarg)
			} else {
				pkgs = append(pkgs, pcarg)
			}
		}
		for _, pkg := range pkgs {
			if !load.SafeArg(pkg) {
				return nil, nil, fmt.Errorf("invalid pkg-config package name: %s", pkg)
			}
		}

		if err := checkPkgConfigFlags("", "pkg-config", pcflags); err != nil {
			return nil, nil, err
		}

		var out []byte
		out, err = sh.runOut(p.Dir, nil, b.PkgconfigCmd(), "--cflags", pcflags, "--", pkgs)
		if err != nil {
			desc := b.PkgconfigCmd() + " --cflags " + strings.Join(pcflags, " ") + " -- " + strings.Join(pkgs, " ")
			return nil, nil, sh.reportCmd(desc, "", out, err)
		}
		if len(out) > 0 {
			cflags, err = splitPkgConfigOutput(bytes.TrimSpace(out))
			if err != nil {
				return nil, nil, err
			}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check every // #cgo pkg-config: directive in your Go source for invalid leading characters
2. Use only standard pkg-config package names (start with a letter, digit, '.', '_', or '/')
3. Verify the package exists: `pkg-config --exists <name>`

Example fix

// before (in .go source)
// #cgo pkg-config: -lmylib
// after
// #cgo pkg-config: mylib

// Validate a cgo pkg-config name like load.SafeArg does
func safePkgConfigName(name string) bool {
    if name == "" { return false }
    c := name[0]
    return '0' <= c && c <= '9' || 'A' <= c && c <= 'Z' ||
        'a' <= c && c <= 'z' || c == '.' || c == '_' ||
        c == '/' || c >= 0x80
}
if !safePkgConfigName(pcName) {
    return fmt.Errorf("unsafe pkg-config name: %s", pcName)
}

When it happens

Trigger: Fires in the cgo flags setup while iterating the pkgs slice (non-flag arguments after --) when load.SafeArg(pkg) returns false for a name from a // #cgo pkg-config: directive.

Common situations: A .go file with `// #cgo pkg-config: -foo`, `// #cgo pkg-config: $VAR`, or any name whose first character is a shell metacharacter or dash.

Related errors

• unexpected shell character %q in pkgconf output
• invalid flag in %s: %s %s (see https://go.dev/s/invalidflag)
• invalid flag in %s: %s (see https://go.dev/s/invalidflag)
• unterminated quoted string in pkgconf output
• broken character escaping in pkgconf output

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