grpc-ecosystem/grpc-gateway · info · ErrNotMatch

not match to the path pattern

Error message

not match to the path pattern

What it means

ErrNotMatch is a sentinel error (errors.Is-able) returned by Pattern.MatchAndEscape and TestMatch when the given HTTP request path does not match the gateway's compiled gRPC HTTP pattern. It is not a crash but a control-flow signal meaning 'this route is not this pattern'.

Source

Thrown at runtime/pattern.go:15

package runtime

import (
	"errors"
	"fmt"
	"strconv"
	"strings"

	"github.com/grpc-ecosystem/grpc-gateway/v2/utilities"
	"google.golang.org/grpc/grpclog"
)

var (
	// ErrNotMatch indicates that the given HTTP request path does not match to the pattern.
	ErrNotMatch = errors.New("not match to the path pattern")
	// ErrInvalidPattern indicates that the given definition of Pattern is not valid.
	ErrInvalidPattern = errors.New("invalid pattern")
)

type MalformedSequenceError string

func (e MalformedSequenceError) Error() string {
	return "malformed path escape " + strconv.Quote(string(e))
}

type op struct {
	code    utilities.OpCode
	operand int
}

// Pattern is a template pattern of http request paths defined in
// https://github.com/googleapis/googleapis/blob/master/google/api/http.proto
type Pattern struct {

View on GitHub (pinned to a58a4436a3)

Solutions

1. Use errors.Is(err, runtime.ErrNotMatch) to distinguish expected non-matches from real errors (e.g. ErrInvalidPattern) and continue with the next pattern
2. Verify the incoming request path and HTTP method match one of the annotations' bindings defined for the service
3. If routing a real request, check that the grpc-gateway runtime mux has a ServeMux option/handler registered for that path

Example fix

_, err := p.MatchAndEscape(components, verb, runtime.EnableEmptyEscapes())
if errors.Is(err, runtime.ErrNotMatch) {
    // try next pattern
    return
}
if err != nil {
    // real error handling
}

// No pre-call validation is practical; match by attempting.
if components == nil || len(components) == 0 && p != nil {
    // pattern with required components will not match empty path
}

func isNotMatch(err error) bool {
    return errors.Is(err, runtime.ErrNotMatch)
}

if err != nil {
    if errors.Is(err, runtime.ErrNotMatch) {
        // expected: try the next pattern / return 404
    } else if errors.Is(err, runtime.ErrInvalidPattern) {
        // real bug: fail fast
    }
}

When it happens

Trigger: Calling pattern.MatchAndEscape(components, verb,Escapes) or TestMatch with a path whose components diverge from the pattern's opcodes: verb mismatch at runtime/pattern.go:157, or fewer components than the pattern requires (pos >= l) at runtime/pattern.go:179.

Common situations: HTTP request hitting the gateway for a URL that doesn't correspond to any registered route; custom routing code probing several patterns where non-match is expected; tests asserting a path should NOT match a pattern (errors.Is(err, runtime.ErrNotMatch)).

Related errors

• empty MIME type
• invalid pattern
• no field path
• no value provided
• failed to parse gRPC API Configuration from YAML in %q: %w

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