thanos-io/thanos · error

reference sequence out of range

Error message

reference sequence %d out of range

What it means

Raised in bucketChunkReader.addLoad when a chunk reference's high 32-bit sequence number (seq = id >> 32) is greater than or equal to the number of partitioned chunkseq loaders (r.toLoad). The chunk ref points to a part of the index that this reader did not initialize — a stale/invalid chunk reference or an index/partition mismatch.

Solutions

1. Verify the block index is consistent with the chunk refs being queried
2. Ensure the block was not deleted/replaced mid-query (re-fetch block meta)
3. Check for corrupted index partitions in the object store

When it happens

Trigger: Thrown at pkg/store/bucket.go:3669 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at pkg/store/bucket.go:3669

		<-r.finishLoadingChks
	}
	r.block.pendingReaders.Done()

	for _, b := range r.chunkBytes {
		r.block.chunkPool.Put(b)
	}
	return nil
}

// addLoad adds the chunk with id to the data set to be fetched.
// Chunk will be fetched and saved to refs[seriesEntry][chunk] upon r.load(refs, <...>) call.
func (r *bucketChunkReader) addLoad(id chunks.ChunkRef, seriesEntry, chunk int) error {
	var (
		seq = int(id >> 32)
		off = uint32(id)
	)
	if seq >= len(r.toLoad) {
		return errors.Errorf("reference sequence %d out of range", seq)
	}
	r.toLoad[seq] = append(r.toLoad[seq], loadIdx{off, seriesEntry, chunk})
	return nil
}

// load loads all added chunks and saves resulting aggrs to refs.
func (r *bucketChunkReader) load(ctx context.Context, res []seriesEntry, aggrs []storepb.Aggr, calculateChunkChecksum bool, bytesLimiter BytesLimiter, tenant string) error {
	r.loadingChunksMtx.Lock()
	r.loadingChunks = true
	r.loadingChunksMtx.Unlock()

	begin := time.Now()
	defer func() {
		r.stats.ChunksDownloadLatencySum += time.Since(begin)

		r.loadingChunksMtx.Lock()
		r.loadingChunks = false
		r.loadingChunksMtx.Unlock()

View on GitHub (pinned to 35b8b99117)