grpc-ecosystem/grpc-gateway · error

unexpected token %q after segments %q

Error message

unexpected token %q after segments %q

What it means

Parser error from parser.topLevelSegments: after consuming all path-template segments, trailing tokens remain before EOF (e.g. an unmatched '}' or stray text in the HttpRule pattern). The template string is not a complete valid path expression; the error shows the first leftover token and the segments parsed so far.

Source

Thrown at internal/httprule/parse.go:131

// parser is a parser of the template syntax defined in github.com/googleapis/googleapis/google/api/http.proto.
type parser struct {
	tokens   []string
	accepted []string
}

// topLevelSegments is the target of this parser.
func (p *parser) topLevelSegments() ([]segment, error) {
	if _, err := p.accept(typeEOF); err == nil {
		p.tokens = p.tokens[:0]
		return []segment{literal(eof)}, nil
	}
	segs, err := p.segments()
	if err != nil {
		return nil, err
	}
	if _, err := p.accept(typeEOF); err != nil {
		return nil, fmt.Errorf("unexpected token %q after segments %q", p.tokens[0], strings.Join(p.accepted, ""))
	}
	return segs, nil
}

func (p *parser) segments() ([]segment, error) {
	s, err := p.segment()
	if err != nil {
		return nil, err
	}

	segs := []segment{s}
	for {
		if _, err := p.accept("/"); err != nil {
			return segs, nil
		}
		s, err := p.segment()
		if err != nil {
			return segs, err

View on GitHub (pinned to a58a4436a3)

Solutions

1. Fix the HttpRule path template to remove trailing/unexpected characters.
2. Balance braces and wildcards; end the template cleanly (e.g. '/v1/things/{id}' or with '=**' variants).

When it happens

Trigger: Thrown at internal/httprule/parse.go:131 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/f7b1a526f425bc28. Report an issue: GitHub.