a non-zero value is required for…

Error message

a non-zero value is required for querier.query-ingesters-within when -querier.parallelise-shardable-queries is enabled

What it means

errInvalidMinShardingLookback is the declared error value used when query sharding (-querier.parallelise-shardable-queries) is enabled without a non-zero querier.query-ingesters-within. Sharding needs a bounded ingester lookback to split queries safely.

Solutions

Set -querier.query-ingesters-within to a non-zero duration (e.g. 13h, larger than your ingester ring's replication)
Or disable -querier.parallelise-shardable-queries
Keep query_ingesters_within aligned with ingester query-ingesters-within settings

Example fix

# before
querier:
  parallelise-shardable-queries: true
# after
querier:
  parallelise-shardable-queries: true
  query-ingesters-within: 13h

Defensive patterns

Strategy: validation

Validate before calling

if cfg.ParalleliseShardableQueries && cfg.QueryIngestersWithin <= 0 {
	return errors.New("set querier.query-ingesters-within before enabling parallelise-shardable-queries")
}

Try / catch

if err := cfg.Validate(qCfg); err != nil {
	if strings.Contains(err.Error(), "query-ingesters-within") {
		cfg.QueryIngestersWithin = model.Duration(13 * time.Hour)
	}
}

Prevention

Always pair parallelise-shardable-queries with a positive query-ingesters-within
Keep it larger than your ingester ring's expected write window
Run config validation in CI pipelines

When it happens

Trigger: Config validation (Validate of the queryrange/querier config chain) with `parallelise_shardable_queries: true` and `query_ingesters_within: 0`, typically at Cortex startup.

Common situations: Operators enabling parallel sharding for performance without setting the ingesters-within window; configs migrated from single-binary setups where query_ingesters_within was never set.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at internal/cortex/querier/queryrange/roundtrip.go:53

	"github.com/weaveworks/common/httpgrpc"
	"github.com/weaveworks/common/user"

	"github.com/thanos-io/thanos/internal/cortex/chunk/cache"
	"github.com/thanos-io/thanos/internal/cortex/querier"
	"github.com/thanos-io/thanos/internal/cortex/tenant"
	"github.com/thanos-io/thanos/internal/cortex/util"
	"github.com/thanos-io/thanos/internal/cortex/util/flagext"
)

const day = 24 * time.Hour

var (
	// PassthroughMiddleware is a noop middleware
	PassthroughMiddleware = MiddlewareFunc(func(next Handler) Handler {
		return next
	})

	errInvalidMinShardingLookback = errors.New("a non-zero value is required for querier.query-ingesters-within when -querier.parallelise-shardable-queries is enabled")
)

// Config for query_range middleware chain.
type Config struct {
	SplitQueriesByInterval time.Duration `yaml:"split_queries_by_interval"`
	AlignQueriesWithStep   bool          `yaml:"align_queries_with_step"`
	ResultsCacheConfig     `yaml:"results_cache"`
	CacheResults           bool `yaml:"cache_results"`
	MaxRetries             int  `yaml:"max_retries"`
	ShardedQueries         bool `yaml:"parallelise_shardable_queries"`
	// List of headers which query_range middleware chain would forward to downstream querier.
	ForwardHeaders flagext.StringSlice `yaml:"forward_headers_list"`
}

// Validate validates the config.
func (cfg *Config) Validate(qCfg querier.Config) error {
	if cfg.CacheResults {
		if cfg.SplitQueriesByInterval <= 0 {

View on GitHub (pinned to 35b8b99117)