{"record":{"id":"63df0ab1c53c6436","repo":"grpc-ecosystem/grpc-gateway","slug":"not-match-to-the-path-pattern","errorCode":null,"errorMessage":"not match to the path pattern","messagePattern":"not match to the path pattern","errorType":"http","errorClass":"ErrNotMatch","httpStatus":404,"severity":"info","filePath":"runtime/pattern.go","lineNumber":15,"sourceCode":"package runtime\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"strconv\"\n\t\"strings\"\n\n\t\"github.com/grpc-ecosystem/grpc-gateway/v2/utilities\"\n\t\"google.golang.org/grpc/grpclog\"\n)\n\nvar (\n\t// ErrNotMatch indicates that the given HTTP request path does not match to the pattern.\n\tErrNotMatch = errors.New(\"not match to the path pattern\")\n\t// ErrInvalidPattern indicates that the given definition of Pattern is not valid.\n\tErrInvalidPattern = errors.New(\"invalid pattern\")\n)\n\ntype MalformedSequenceError string\n\nfunc (e MalformedSequenceError) Error() string {\n\treturn \"malformed path escape \" + strconv.Quote(string(e))\n}\n\ntype op struct {\n\tcode    utilities.OpCode\n\toperand int\n}\n\n// Pattern is a template pattern of http request paths defined in\n// https://github.com/googleapis/googleapis/blob/master/google/api/http.proto\ntype Pattern struct {","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/grpc-ecosystem/grpc-gateway/blob/a58a4436a376a4bcc7d8f10c4d4f919a8438bba9/runtime/pattern.go#L1-L33","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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)).","solutions":["Use errors.Is(err, runtime.ErrNotMatch) to distinguish expected non-matches from real errors (e.g. ErrInvalidPattern) and continue with the next pattern","Verify the incoming request path and HTTP method match one of the annotations' bindings defined for the service","If routing a real request, check that the grpc-gateway runtime mux has a ServeMux option/handler registered for that path"],"exampleFix":"_, err := p.MatchAndEscape(components, verb, runtime.EnableEmptyEscapes())\nif errors.Is(err, runtime.ErrNotMatch) {\n    // try next pattern\n    return\n}\nif err != nil {\n    // real error handling\n}","handlingStrategy":"try-catch","validationCode":"// No pre-call validation is practical; match by attempting.\nif components == nil || len(components) == 0 && p != nil {\n    // pattern with required components will not match empty path\n}","typeGuard":"func isNotMatch(err error) bool {\n    return errors.Is(err, runtime.ErrNotMatch)\n}","tryCatchPattern":"if err != nil {\n    if errors.Is(err, runtime.ErrNotMatch) {\n        // expected: try the next pattern / return 404\n    } else if errors.Is(err, runtime.ErrInvalidPattern) {\n        // real bug: fail fast\n    }\n}","preventionTips":["Always test route non-matches with errors.Is, never string comparison of err.Error()","Log the request path and verb when no pattern matches to ease 404 debugging","Generate bindings from proto annotations rather than hand-built patterns"],"tags":["go","grpc-gateway","routing","sentinel-error"],"backgroundTag":"route-not-matched","analyzedSha":"a58a4436a376a4bcc7d8f10c4d4f919a8438bba9","analyzedAt":"2026-09-02T10:28:31.537Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T16:17:10.729Z"}