malformed prefix %q: escape sequence %q must contain two hex

Error message

malformed prefix %q: escape sequence %q must contain two hex digits

What it means

`PrefixToPath` decodes `%xx` escape sequences in symbol table names. This error fires when the two characters following `%` are not valid hexadecimal digits (e.g., `%zz` or `%j3`). The code calls `strconv.ParseUint(s[i+1:i+3], 16, 8)` and on failure reports the specific invalid escape sequence.

Source

Thrown at src/cmd/internal/objabi/path.go:71

	}

	p := make([]byte, 0, len(s))
	for i := 0; i < len(s); {
		if s[i] != '%' {
			p = append(p, s[i])
			i++
			continue
		}
		if i+2 >= len(s) {
			// Not enough characters remaining to be a valid escape
			// sequence.
			return "", fmt.Errorf("malformed prefix %q: escape sequence must contain two hex digits", s)
		}

		b, err := strconv.ParseUint(s[i+1:i+3], 16, 8)
		if err != nil {
			// Not a valid escape sequence.
			return "", fmt.Errorf("malformed prefix %q: escape sequence %q must contain two hex digits", s, s[i:i+3])
		}

		p = append(p, byte(b))
		i += 3
	}
	return string(p), nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Ensure all symbol names were encoded with `PathToPrefix` before being stored.
If the `%` is literal data, encode it properly: `PathToPrefix` turns `%` into `%25`.
Sanitize or reject externally-provided symbol names before decoding.

Example fix

// before — raw string with literal % not encoded
s := "pkg%name"
path, err := objabi.PrefixToPath(s)  // fails: %n is not valid hex

// after — encode first, then decode is lossless
encoded := objabi.PathToPrefix("pkg%name")  // → "pkg%25name"
path, err := objabi.PrefixToPath(encoded)    // → "pkg%name"

Defensive patterns

Strategy: validation

Validate before calling

// Validate that all %xx sequences contain valid hex digits
func validateHexEscapes(s string) error {
    for i := 0; i < len(s); i++ {
        if s[i] == '%' {
            if i+2 >= len(s) {
                return fmt.Errorf("incomplete escape at %d", i)
            }
            _, err := strconv.ParseUint(s[i+1:i+3], 16, 8)
            if err != nil {
                return fmt.Errorf("invalid hex escape %q at position %d", s[i:i+3], i)
            }
            i += 2
        }
    }
    return nil
}

Try / catch

func safePrefixToPath(s string) (string, error) {
    path, err := objabi.PrefixToPath(s)
    if err != nil && strings.Contains(err.Error(), "must contain two hex digits") {
        return "", fmt.Errorf("corrupt symbol name %q: %w", s, err)
    }
    return path, err
}

Prevention

Encode all paths through PathToPrefix to guarantee valid %xx sequences.
If reading symbol names from external/debug sections, validate escape sequences before decoding.
Reject or quarantine symbol names containing literal % that were not produced by PathToPrefix.

When it happens

Trigger: Calling `objabi.PrefixToPath(s)` where `s` contains `%` followed by characters that are not hex digits (0-9, a-f, A-F). For example, a symbol name containing a literal `%` that was not properly escaped by `PathToPrefix`.

Common situations: Hand-constructed or externally-generated symbol names containing unescaped `%`. Strings from a non-Go source that use `%` for a different purpose. Corrupted archive data. A tool that reads symbol names from DWARF or other debug sections without going through the proper encoding layer.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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