{"record":{"id":"33f52dd84bee60f9","repo":"thanos-io/thanos","slug":"unrecognized-matcher-type","errorCode":null,"errorMessage":"unrecognized matcher type","messagePattern":"unrecognized matcher type","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/store/prometheus.go","lineNumber":195,"sourceCode":"\n\tshardMatcher := r.ShardInfo.Matcher(&p.buffers)\n\tdefer shardMatcher.Close()\n\n\tq := &prompb.Query{StartTimestampMs: r.MinTime, EndTimestampMs: r.MaxTime}\n\tfor _, m := range matchers {\n\t\tpm := &prompb.LabelMatcher{Name: m.Name, Value: m.Value}\n\n\t\tswitch m.Type {\n\t\tcase labels.MatchEqual:\n\t\t\tpm.Type = prompb.LabelMatcher_EQ\n\t\tcase labels.MatchNotEqual:\n\t\t\tpm.Type = prompb.LabelMatcher_NEQ\n\t\tcase labels.MatchRegexp:\n\t\t\tpm.Type = prompb.LabelMatcher_RE\n\t\tcase labels.MatchNotRegexp:\n\t\t\tpm.Type = prompb.LabelMatcher_NRE\n\t\tdefault:\n\t\t\treturn errors.New(\"unrecognized matcher type\")\n\t\t}\n\t\tq.Matchers = append(q.Matchers, pm)\n\t}\n\n\tqueryPrometheusSpan, ctx := tracing.StartSpan(s.Context(), \"query_prometheus\")\n\tqueryPrometheusSpan.SetTag(\"query.request\", q.String())\n\n\thttpResp, err := p.startPromRemoteRead(ctx, q)\n\tif err != nil {\n\t\tqueryPrometheusSpan.Finish()\n\t\treturn errors.Wrap(err, \"query Prometheus\")\n\t}\n\n\t// Negotiate content. We requested streamed chunked response type, but still we need to support old versions of\n\t// remote read.\n\tcontentType := httpResp.Header.Get(\"Content-Type\")\n\tif strings.HasPrefix(contentType, \"application/x-protobuf\") {\n\t\treturn p.handleSampledPrometheusResponse(s, httpResp, queryPrometheusSpan, extLset, enableChunkHashCalculation, extLsetToRemove)","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/store/prometheus.go#L177-L213","documentation":"PrometheusStore.Series converts labels matchers to Prometheus remote-read matcher types. If a matcher implements labels.Matcher but its Type() is not EQ/NEQ/RE/NRE, the switch hits default and returns 'unrecognized matcher type'. This guards against unsupported or future matcher kinds.","triggerScenarios":"Building a Series query whose selectors include a matcher type outside the four mapped ones (e.g. a custom MatchType implementation or newly added upstream match type).","commonSituations":"Client libraries or instrumentation adding new matcher types; custom code constructing labels.Matcher with an out-of-range MatchType; version skew where a newer PromQL feature is sent to an older Thanos store.","solutions":["Inspect the PromQL selectors used and restrict them to =, !=, =~, !~ matchers.","Upgrade Thanos/store so it knows any newer matcher types.","Audit custom code that constructs labels.Matcher values directly."],"exampleFix":"// before\nmatcher := labels.MustNewMatcher(labels.MatchType(\"like\"), \"job\", \"foo\") // invalid\n// after\nmatcher := labels.MustNewMatcher(labels.MatchRegexp, \"job\", \"foo\")","handlingStrategy":"validation","validationCode":"valid := []labels.MatchType{labels.MatchEqual, labels.MatchNotEqual, labels.MatchRegexp, labels.MatchNotRegexp}\nfor _, m := range matchers {\n    if !slices.Contains(valid, m.Type) {\n        return fmt.Errorf(\"matcher %q has unsupported type %q\", m.Name, m.Type)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := s.Series(ctx, req); err != nil {\n    if strings.Contains(err.Error(), \"unrecognized matcher type\") {\n        // rewrite/strip the offending selector client-side and retry\n    }\n    return err\n}","preventionTips":["Only issue =, !=, =~, !~ selectors against remote read stores.","Keep client PromQL libraries and Thanos versions aligned.","Validate user-supplied selectors before dispatching store queries."],"tags":["prometheus","remote-read","matcher","query"],"backgroundTag":"invalid-enum-value","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}