grpc-ecosystem/grpc-gateway · error

invalid character in path segment: %q(%U)

Error message

invalid character in path segment: %q(%U)

What it means

Lexical-validation error from expectPChars: a character in the path-template literal is not an allowed RFC 3986 pchar (unreserved, sub-delims, ':', '@', or start of a percent-encoding). The literal contains a character such as space, '?' or ']' that http.proto path templates forbid; the error names the character and code point.

Source

Thrown at internal/httprule/parse.go:324

		case 'A' <= r && r <= 'Z':
			continue
		case 'a' <= r && r <= 'z':
			continue
		case '0' <= r && r <= '9':
			continue
		}
		switch r {
		case '-', '.', '_', '~':
			// unreserved
		case '!', '$', '&', '\'', '(', ')', '*', '+', ',', ';', '=':
			// sub-delims
		case ':', '@':
			// rest of pchar
		case '%':
			// pct-encoded
			st = pct1
		default:
			return fmt.Errorf("invalid character in path segment: %q(%U)", r, r)
		}
	}
	if st != init {
		return fmt.Errorf("invalid percent-encoding in %q", t)
	}
	return nil
}

// expectIdent determines if "ident" is a valid identifier in .proto schema ([[:alpha:]_][[:alphanum:]_]*).
func expectIdent(ident string) error {
	if ident == "" {
		return errors.New("empty identifier")
	}
	for pos, r := range ident {
		switch {
		case '0' <= r && r <= '9':
			if pos == 0 {
				return fmt.Errorf("identifier starting with digit: %s", ident)

View on GitHub (pinned to a58a4436a3)

Solutions

1. Remove or percent-encode the disallowed character in the HttpRule path template.
2. Use only unreserved/sub-delims characters, ':', '@', or valid %XX escapes in literals.

When it happens

Trigger: Thrown at internal/httprule/parse.go:324 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

AI-assisted analysis of grpc-ecosystem/grpc-gateway@a58a4436a3 (2026-09-02). Data as JSON: /api/errors/f61f5809c2462aae. Report an issue: GitHub.