unexpected shell character %q in pkgconf output

Error message

unexpected shell character %q in pkgconf output

What it means

When parsing pkg-config (--cflags/--libs) output into compiler flags, the go command runs a shell-quoting parser that accepts a safe subset of characters. If a character matches none of the handled cases (| & ; < > ( ) $ ` \ " ' and whitespace handling) it falls through and is rejected. This is a security guard preventing pkg-config output from injecting shell commands or unsafe tokens into the compiler invocation.

Source

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

			// “preserve the literal value of each character”
			flag = append(flag, c)
			continue
		case '"':
			// “preserve the literal value of all characters within the double-quotes,
			// with the exception of …”
			switch c {
			case '`', '$', '\\':
			default:
				flag = append(flag, c)
				continue
			}
		}

		// “The application shall quote the following characters if they are to
		// represent themselves:”
		switch c {
		case '|', '&', ';', '<', '>', '(', ')', '$', '`':
			return nil, fmt.Errorf("unexpected shell character %q in pkgconf output", c)

		case '\\':
			// “A <backslash> that is not quoted shall preserve the literal value of
			// the following character, with the exception of a <newline>.”
			escaped = true
			continue

		case '"', '\'':
			quote = c
			didQuote = true
			continue

		case ' ', '\t', '\n':
			if len(flag) > 0 || didQuote {
				flags = append(flags, string(flag))
			}
			flag, didQuote = flag[:0], false
			continue

View on GitHub (pinned to b6b368adc5)

Solutions

Inspect the .pc file: run `pkg-config --cflags <pkg>` and look for unusual characters
Edit the .pc file to remove or properly quote the offending characters in Cflags/Libs
Point PKG_CONFIG_PATH at a directory with corrected .pc files

Example fix

# before (.pc file contains)
Cflags: -I/usr/include/foo*
# after (remove glob characters)
Cflags: -I/usr/include/foo

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check pkg-config output for characters the go parser rejects
out, err := exec.Command("pkg-config", append([]string{"--cflags"}, pkgs...)...).Output()
if err != nil { return err }
for _, b := range out {
    switch b {
    case '*', '?', '{', '}', '!', '~', '\\n', '\\r':
        return fmt.Errorf("pkg-config output has unsafe char %q", b)
    }
}

Prevention

Audit .pc files for glob/tilde/newline characters in Cflags and Libs
Prefer pkg-config modules shipped by the system over hand-written .pc files
Run `pkg-config --cflags --libs <pkg>` and eyeball the output before building with cgo

When it happens

Trigger: Fires in the pkg-config output parser at the default fall-through of the shell-character switch, when a character (e.g. *, ?, {, }, !, ~) appears that the parser does not recognize as safely quotable.

Common situations: A hand-edited or generated .pc file whose Cflags/Libs lines contain glob characters, tildes, or other shell metacharacters the parser refuses to pass through.

Related errors

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