thanos-io/thanos · error

series not found

Error message

series %d not found

What it means

LoadSeriesForTime looks up the raw bytes for a series reference in the reader's already-loaded series map (loadedSeries, populated by Series()). If the ref was never loaded — or was loaded in a different bucketIndexReader instance — the reference cannot be resolved and this error is returned instead of decoding. It is a programming/usage error in the query path rather than a data problem.

Solutions

1. Ensure Series() is called on the same bucketIndexReader for all refs before LoadSeriesForTime
2. Verify series refs originate from postings of the same block (per-block readers are not interchangeable)
3. If this comes from a querier component, reload postings and series for the query instead of reusing refs across attempts
4. Check Thanos version for known bugs where refs outlive their reader lifecycle and upgrade if affected

b, ok := r.loadedSeries[ref]
if !ok {
	// ref not loaded by this reader: re-run postings+Series() before LoadSeriesForTime
}

func (r *bucketIndexReader) hasSeries(ref storage.SeriesRef) bool { _, ok := r.loadedSeries[ref]; return ok }

ok, err := reader.LoadSeriesForTime(ref, &lset, &chks, false, mint, maxt)
if err != nil && strings.Contains(err.Error(), "not found") {
	if _, lerr := reader.Series(ctx, tenant, []storage.SeriesRef{ref}); lerr == nil {
		ok, err = reader.LoadSeriesForTime(ref, &lset, &chks, false, mint, maxt) // retry after loading
	}
}

When it happens

Trigger: Calling LoadSeriesForTime with a storage.SeriesRef that was not previously returned by postings lookup and loaded via Series() on the same reader; using refs from a different block; reader state dropped between calls.

Common situations: PromQL/engine fetching samples with stale series refs after a new querier round; refs obtained from postings of block A used against block B; timeouts that discarded loadedSeries before the refetch call.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• read series range
• reading series length failed
• invalid remaining size, even after refetch, remaining
• create bucket compactor
• raw resolution must be higher than the minimum block size…

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

Appendix: source

Thrown at pkg/store/bucket.go:3504

		parts = append(parts, p)
	}
	return parts
}

type symbolizedLabel struct {
	name, value uint32
}

// LoadSeriesForTime populates the given symbolized labels for the series identified by the reference if at least one chunk is within
// time selection.
// LoadSeriesForTime also populates chunk metas slices if skipChunks if set to false. Chunks are also limited by the given time selection.
// LoadSeriesForTime returns false, when there are no series data for given time range.
//
// Error is returned on decoding error or if the reference does not resolve to a known series.
func (r *bucketIndexReader) LoadSeriesForTime(ref storage.SeriesRef, lset *[]symbolizedLabel, chks *[]chunks.Meta, skipChunks bool, mint, maxt int64) (ok bool, err error) {
	b, ok := r.loadedSeries[ref]
	if !ok {
		return false, errors.Errorf("series %d not found", ref)
	}

	r.stats.add(SeriesTouched, 1, len(b))
	return decodeSeriesForTime(b, lset, chks, skipChunks, mint, maxt)
}

// Close released the underlying resources of the reader.
func (r *bucketIndexReader) Close() error {
	r.block.pendingReaders.Done()

	if r.postings != nil {
		putPostingsSlice(r.postings)
	}
	return nil
}

func (b *blockSeriesClient) CloseSend() error {
	return nil

View on GitHub (pinned to 35b8b99117)