thanos-io/thanos · info

range not found

Error message

range not found

What it means

Sentinel error NotFoundRangeErr returned by Reader.PostingsOffset when the index header has no posting range for the given label name/value pair. Signals a legitimate miss (symbol/label not in the index), used by callers for existence checks, not an unexpected failure.

Solutions

1. Treat it as 'no data for this label pair in this block' and skip the block (errors.Is(err, indexheader.NotFoundRangeErr))
2. Verify the label name/value spelling and casing
3. Check you are querying blocks that actually cover the requested data

Example fix

// before
rng, err := br.PostingsOffset("job", "node")
if err != nil { return err }
// after
rng, err := br.PostingsOffset("job", "node")
if errors.Is(err, indexheader.NotFoundRangeErr) { return nil // block lacks this posting
}
if err != nil { return err }

rng, err := br.PostingsOffset(name, value)
if errors.Is(err, indexheader.NotFoundRangeErr) { return nil /* expected: label pair absent */ }
if err != nil { return err }

When it happens

Trigger: Calling br.PostingsOffset("name","value") for a label name or value combination that does not exist in the block's postings table (e.g. "not-existing","1" in tests).

Common situations: Querier/store-gateway asking a block for series that this block simply doesn't contain; typos in label names; querying time-ranged blocks outside their data.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• postings
• read postings table
• get postings offset entry
• marker not found
• create compactor

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

Appendix: source

Thrown at pkg/block/indexheader/header.go:15

// Copyright (c) The Thanos Authors.
// Licensed under the Apache License 2.0.

package indexheader

import (
	"context"
	"io"

	"github.com/pkg/errors"
	"github.com/prometheus/prometheus/tsdb/index"
)

// NotFoundRangeErr is an error returned by PostingsOffset when there is no posting for given name and value pairs.
var NotFoundRangeErr = errors.New("range not found")

// Reader is an interface allowing to read essential, minimal number of index fields from the small portion of index file called header.
type Reader interface {
	io.Closer

	// IndexVersion returns version of index.
	IndexVersion() (int, error)

	// PostingsOffsets returns start and end offsets for postings for given name and values.
	// Input values need to be sorted.
	// If the requested label name doesn't exist, then no posting and error will be returned.
	// If the requested label name exists, but some values don't exist, the corresponding index range
	// will be set to -1 for both start and end.
	PostingsOffsets(name string, value ...string) ([]index.Range, error)

	// PostingsOffset returns start and end offsets of postings for given name and value.
	// The end offset might be bigger than the actual posting ending, but not larger than the whole index file.
	// NotFoundRangeErr is returned when no index can be found for given name and value.

View on GitHub (pinned to 35b8b99117)