thanos-io/thanos · error

failed to convert matchers

Error message

failed to convert matchers

What it means

Inside the Status server's TSDB statistics getter, gRPC label matchers are converted to Prometheus matchers with storepb.MatchersToPromMatchers. If any matcher has an invalid type/value combination, the conversion fails and the error is wrapped with 'failed to convert matchers' and returned to the RPC caller.

Solutions

1. Validate the regex patterns in your matchers compile under RE2 (Go regexp) before sending.
2. Check that each matcher's MatchType is a supported storepb type (EQ, NEQ, RE, NRE).
3. Fix the client code building the matchers and retry the request.
4. If using a third-party tool, upgrade it to a version that emits valid matchers.

Example fix

// before
matcher := &storepb.LabelMatcher{Type: storepb.LabelMatcher_RE, Name: "job", Value: "("} // invalid regex
// after
matcher := &storepb.LabelMatcher{Type: storepb.LabelMatcher_RE, Name: "job", Value: "prometheus.*"}

for _, m := range matchers {
  if _, err := regexp.Compile(m.Value); err != nil {
    return fmt.Errorf("invalid matcher regex %q for %q: %w", m.Value, m.Name, err)
  }
}
if _, err := storepb.MatchersToPromMatchers(matchers...); err != nil { return err }

func validMatcherType(t storepb.LabelMatcher_Type) bool {
  switch t {
  case storepb.LabelMatcher_EQ, storepb.LabelMatcher_NEQ, storepb.LabelMatcher_RE, storepb.LabelMatcher_NRE:
    return true
  }
  return false
}

stats, err := statusClient.TSDBStatistics(ctx, req)
if err != nil && strings.Contains(err.Error(), "failed to convert matchers") {
  return fmt.Errorf("fix client-side matchers (type/regex): %w", err)
}

When it happens

Trigger: Sending a TSDB statistics request whose []storepb.LabelMatcher contains an invalid matcher — e.g. an unknown matcher type or a regex matcher with a pattern that does not compile as a Prometheus regexp.

Common situations: Client tooling constructing matchers with a wrong MatchType enum value; regex patterns with syntax Prometheus's regex engine (RE2) rejects; corrupted/manual protobuf requests.

Related errors

• failed to convert matchers
• failed to convert matchers
• endpoint
• validate relabel config
• InvalidArgument

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/7dc8a278ebedb876. Report an issue: GitHub.

Appendix: source

Thrown at cmd/thanos/receive.go:421

					}, nil
				}
				return nil, errors.New("Not ready")
			}),
			info.WithExemplarsInfoFunc(),
			info.WithStatusInfoFunc(),
		)

		statusSrv := status.NewServer(
			component.Receive.String(),
			status.WithTSDBStatisticsGetter(
				status.TSDBStatisticsGetterFunc(func(limit int, matchers []storepb.LabelMatcher) (map[string]tsdb.Stats, error) {
					if !httpProbe.IsReady() {
						return nil, errors.New("not ready")
					}

					promMatchers, err := storepb.MatchersToPromMatchers(matchers...)
					if err != nil {
						return nil, errors.Wrap(err, "failed to convert matchers")
					}

					// Build the list of tenant IDs if the request matches
					// against exact tenant values only.
					var tenantIDs []string
					for _, promMatcher := range promMatchers {
						if promMatcher.Name != conf.tenantLabelName {
							continue
						}

						if promMatcher.Type != labels.MatchEqual {
							tenantIDs = nil
							break
						}

						tenantIDs = append(tenantIDs, promMatcher.Value)
					}

View on GitHub (pinned to 35b8b99117)