thanos-io/thanos · error

preload series

Error message

preload series

What it means

Wraps IndexReader.PreloadSeries failure in blockSeriesClient.series. PreloadSeries fetches the series data referenced by the expanded postings batch into the index reader's cache before per-series loading. Failures typically stem from index fetch or decode errors and are bounded by the bytes limiter.

Solutions

1. Check the wrapped root error; for byte-limit exhaustion, raise the store's per-request size limits or narrow the query time/matcher range.
2. Verify the block index integrity with 'thanos tools bucket verify' and remove corrupted blocks.
3. Retry on transient object-store failures; check bucket latency/limits.
4. Reduce query fan-out concurrency to avoid store resource exhaustion.

// Estimate request size before issuing wide queries
span := maxt - mint
if span > maxQuerySpan {
	return fmt.Errorf("query span %d exceeds limit %d; narrow the range", span, maxQuerySpan)
}

if err := runSeriesQuery(ctx, q); err != nil && strings.Contains(err.Error(), "preload series") {
	if isBytesLimitExceeded(err) {
		return splitAndRetry(ctx, q) // split query into smaller time windows
	}
	return err
}

When it happens

Trigger: Series streaming calls preload with a postings batch; indexr.PreloadSeries(ctx, postingsBatch, bytesLimiter, tenant) fails on fetching series data from the block index, decoding corrupt series sections, or exhausting the request bytes limit.

Common situations: Corrupted block index sections, object-store timeouts under heavy query load, queries too large for the configured per-request bytes limit, blocks removed from the bucket mid-query.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• get index version
• read series
• Lookup labels symbols
• add chunk load
• label names for block

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

Appendix: source

Thrown at pkg/store/bucket.go:1306

				}
				if v >= 2 {
					for i := range b.expandedPostings {
						b.expandedPostings[i] = b.expandedPostings[i] / 16
					}
				}
			}
			b.indexr.storeExpandedPostingsToCache(b.blockMatchers, index.NewListPostings(b.expandedPostings), len(b.expandedPostings), tenant)
		}
		return nil
	}

	b.indexr.reset(len(postingsBatch))
	if !b.skipChunks {
		b.chunkr.reset()
	}

	if err := b.indexr.PreloadSeries(b.ctx, postingsBatch, b.bytesLimiter, b.tenant); err != nil {
		return errors.Wrap(err, "preload series")
	}

	seriesMatched := 0
	b.entries = b.entries[:0]
OUTER:
	for i := range postingsBatch {
		if err := b.ctx.Err(); err != nil {
			return err
		}
		hasMatchedChunks, err := b.indexr.LoadSeriesForTime(postingsBatch[i], &b.symbolizedLset, &b.chkMetas, b.skipChunks, b.mint, b.maxt)
		if err != nil {
			return errors.Wrap(err, "read series")
		}
		// Skip getting series symbols if we know there is no matched chunks
		// and lazy expanded posting not enabled.
		if !lazyExpandedPosting && !hasMatchedChunks {
			continue
		}

View on GitHub (pinned to 35b8b99117)