split queries or split threshold interval should be greater…

Error message

split queries or split threshold interval should be greater than 0 when caching is enabled

What it means

Config.Validate enforces that when the query_range results cache is enabled, queries are split into cacheable chunks: either a static QueryRangeConfig.SplitQueriesByInterval > 0 or a dynamic split threshold must be set. Otherwise caching cannot work and validation returns this error at frontend startup.

Solutions

Set --query-range.split-queries-by-interval to a positive duration (e.g. 1d).
Or enable dynamic query splitting with a positive --query-range.dynamic-split-threshold so isDynamicSplitSet() is true.
Or disable the results cache if splitting is not desired.

Example fix

// before
queryRangeFlags := []string{"--query-range.response-cache-config-file=cache.yml"}
// after
queryRangeFlags := []string{"--query-range.response-cache-config-file=cache.yml", "--query-range.split-queries-by-interval=24h"}

Defensive patterns

Strategy: validation

Validate before calling

// before startup
if cachingEnabled && splitInterval <= 0 && dynamicSplitThreshold <= 0 {
    return errors.New("enable --query-range.split-queries-by-interval or --query-range.dynamic-split-threshold when response caching is on")
}

Try / catch

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "split queries or split threshold") {
        return fmt.Errorf("add a split flag when caching is enabled: %w", err)
    }
    return err
}

Prevention

Always pair --query-range.response-cache-config with --query-range.split-queries-by-interval.
Add a smoke test that runs the frontend with production flags in CI.
Re-check flags after Thanos upgrades for changed defaults.

When it happens

Trigger: QueryRangeConfig.ResultsCacheConfig is non-nil (caching enabled) while SplitQueriesByInterval <= 0 and isDynamicSplitSet() returns false (no dynamic split threshold configured).

Common situations: Operator enables response caching via --query-range.response-cache-config but forgets --query-range.split-queries-by-interval, or sets it to 0/negative after a version upgrade where defaults changed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at pkg/queryfrontend/config.go:264

	// PartialResponseStrategy is the default strategy used
	// when parsing thanos query request.
	PartialResponseStrategy bool
	DefaultTimeRange        time.Duration

	ResultsCacheConfig *queryrange.ResultsCacheConfig
	CachePathOrContent extflag.PathOrContent

	SplitQueriesByInterval time.Duration
	MaxRetries             int

	Limits *cortexvalidation.Limits
}

// Validate a fully initialized config.
func (cfg *Config) Validate() error {
	if cfg.QueryRangeConfig.ResultsCacheConfig != nil {
		if cfg.QueryRangeConfig.SplitQueriesByInterval <= 0 && !cfg.isDynamicSplitSet() {
			return errors.New("split queries or split threshold interval should be greater than 0 when caching is enabled")
		}
		// This is instantiated just to make the QFE config comply with validation against the Cortex Querier,
		// but in Thanos we don't use this configuration at all.
		ignoredQueryConfig := querier.Config{
			EnablePerStepStats: cfg.QueryRangeConfig.ResultsCacheConfig.CacheQueryableSamplesStats,
		}
		if err := cfg.QueryRangeConfig.ResultsCacheConfig.Validate(ignoredQueryConfig); err != nil {
			return errors.Wrap(err, "invalid ResultsCache config for query_range tripperware")
		}
	}

	if cfg.isDynamicSplitSet() && cfg.isStaticSplitSet() {
		return errors.New("split queries interval and dynamic query split interval cannot be set at the same time")
	}

	if cfg.isDynamicSplitSet() {

		if err := cfg.validateDynamicSplitParams(); err != nil {

View on GitHub (pinned to 35b8b99117)