querier.cache-results may only be enabled in conjunction…

Error message

querier.cache-results may only be enabled in conjunction with querier.split-queries-by-interval. Please set the latter

What it means

Config.Validate of the queryrange middleware chain rejects querier.cache-results=true when split_queries_by_interval is not set. Cached results are only meaningful per split interval, so caching requires query splitting to be configured.

Solutions

Set -querier.split-queries-by-interval to a positive duration (e.g. 24h)
Or disable -querier.cache-results if splitting is not wanted
Review the full queryrange Config.Validate chain since further nested validation follows

Example fix

# before
querier:
  cache-results: true
# after
querier:
  cache-results: true
  split-queries-by-interval: 24h

Defensive patterns

Strategy: validation

Validate before calling

if cfg.CacheResults && cfg.SplitQueriesByInterval <= 0 {
	return errors.New("cache-results requires split-queries-by-interval > 0")
}

Try / catch

if err := cfg.Validate(qCfg); err != nil {
	if strings.Contains(err.Error(), "split-queries-by-interval") {
		cfg.SplitQueriesByInterval = model.Duration(24 * time.Hour)
	}
}

Prevention

Enable cache-results and split-queries-by-interval together in templates
Choose an interval matching dashboard time ranges (typically 24h)
Validate configs before deployment

When it happens

Trigger: Startup validation with `cache_results: true` and `split_queries_by_interval: 0` (or the flag -querier.split-queries-by-interval unset).

Common situations: Enabling the results cache to cut query load but forgetting the split interval; copying partial config snippets from docs.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

)

// 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 {
			return errors.New("querier.cache-results may only be enabled in conjunction with querier.split-queries-by-interval. Please set the latter")
		}
		if err := cfg.ResultsCacheConfig.Validate(qCfg); err != nil {
			return errors.Wrap(err, "invalid ResultsCache config")
		}
	}
	return nil
}

// HandlerFunc is like http.HandlerFunc, but for Handler.
type HandlerFunc func(context.Context, Request) (Response, error)

// Do implements Handler.
func (q HandlerFunc) Do(ctx context.Context, req Request) (Response, error) {
	return q(ctx, req)
}

// Handler is like http.Handle, but specifically for Prometheus query_range calls.
type Handler interface {

View on GitHub (pinned to 35b8b99117)