thanos-io/thanos · error

InvalidArgument

InvalidArgument

Error message

no matchers specified (excluding external labels)

What it means

LocalStore's Series validates that at least one matcher (besides external labels) is provided and returns a gRPC InvalidArgument status error "no matchers specified (excluding external labels)" when the list is empty. The Thanos StoreAPI requires matcher-based filtering; a match-all query is not permitted against this store.

Solutions

1. Add at least one label matcher to the SeriesRequest.
2. Check client-side filtering that strips external-label matchers — don't end up with zero matchers.
3. If you truly want everything, query with a broad matcher like {__name__!=""} where supported.
4. Fix tooling that builds the request to always emit >= 1 non-external-label matcher.

Example fix

// before
req := &storepb.SeriesRequest{MinTime: t0, MaxTime: t1}
// after
req := &storepb.SeriesRequest{MinTime: t0, MaxTime: t1, Matchers: []labelpb.Matcher{{Type: labelpb.MatchType_EQ, Name: "__name__", Value: "up"}}}

if len(req.Matchers) == 0 {
  return status.Error(codes.InvalidArgument, "no matchers specified")
}

if s, ok := status.FromError(err); ok && s.Code() == codes.InvalidArgument && strings.Contains(s.Message(), "no matchers") {
  // fix request construction before retrying
}

When it happens

Trigger: Calling the StoreAPI Series RPC with a req whose matchers list, after removing those matching external labels, is empty.

Common situations: Clients constructing SeriesRequest with only external-label matchers or an empty matcher list; PrometheusQuerier misconfiguration sending global queries to a store; tooling generating requests programmatically with no matchers.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• endpoint
• failed to convert matchers
• failed to convert matchers
• failed to parse the template
• failed to execute the template

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

Appendix: source

Thrown at pkg/store/local.go:142

	if atEOF {
		return len(data), data, nil
	}
	// Incomplete; get more bytes.
	return len(delim), nil, nil
}

// Series returns all series for a requested time range and label matcher. The returned data may
// exceed the requested time bounds.
func (s *LocalStore) Series(r *storepb.SeriesRequest, srv storepb.Store_SeriesServer) error {
	match, matchers, err := matchesExternalLabels(r.Matchers, s.extLabels, storecache.NoopMatchersCache)
	if err != nil {
		return status.Error(codes.InvalidArgument, err.Error())
	}
	if !match {
		return nil
	}
	if len(matchers) == 0 {
		return status.Error(codes.InvalidArgument, errors.New("no matchers specified (excluding external labels)").Error())
	}

	var chosen []int
	for si, series := range s.series {
		lbls := labelpb.ZLabelsToPromLabels(series.Labels)
		var noMatch bool
		for _, m := range matchers {
			extValue := lbls.Get(m.Name)
			if extValue == "" {
				continue
			}
			if !m.Matches(extValue) {
				noMatch = true
				break
			}
		}
		if noMatch {
			continue

View on GitHub (pinned to 35b8b99117)