thanos-io/thanos · error

initializing the query range cache config

Error message

initializing the query range cache config

What it means

This error wraps failures from queryfrontend.NewCacheConfig when parsing the query-range results cache YAML (via --query-range-cache-config-file or inline content). NewCacheConfig validates backend type (in-memory, memcached, redis) and its options. Thanos wraps it to indicate the query-range cache config specifically failed.

Solutions

1. Check the wrapped underlying error for the exact field/type failure.
2. Validate the cache backend type is one of the supported values (in-memory, memcached, redis).
3. Validate YAML syntax and field types against the CacheConfig schema.
4. Test the same YAML with a minimal Thanos setup before deploying.

Example fix

// before
memory:
  max_size_items: 0
type: memcached-doesnotexist
// after
memcached:
  addresses: [dnssrvnoa+memcached:11211]
type: memcached

type cacheProbe struct {
  Type string `yaml:"type"`
}
var p cacheProbe
if err := yaml.Unmarshal(yamlContent, &p); err != nil || p.Type == "" {
  return errors.New("cache config needs a valid 'type' field")
}

if _, err := queryfrontend.NewCacheConfig(logger, yamlContent); err != nil {
  log.Fatalf("query range cache config invalid: %v", err)
}

When it happens

Trigger: Supplying a query-range cache config YAML that is invalid: unknown backend type, missing backend options, wrong field types, or unparseable YAML.

Common situations: Mixing Cortex cache schemas across versions, memcached addresses left empty, redis config copied from another component with unsupported fields, or YAML syntax errors.

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

• initializing the labels cache config
• parsing config YAML file
• marshal content of cache backend configuration
• parsing config YAML file
• marshal content of cache backend configuration

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

Appendix: source

Thrown at cmd/thanos/query_frontend.go:278

		}

		cfg.orgIdHeaders = append(cfg.orgIdHeaders, cfg.TenantHeader)
	}

	// Temporarily manually adding the default tenant header into the list of headers to forward and org id headers.
	// This facilitates the transition from org id to tenant id with minimal amount of changes.
	cfg.ForwardHeaders = append(cfg.ForwardHeaders, tenancy.DefaultTenantHeader)
	// TODO: This should be removed once the org id header is fully removed in Thanos.
	cfg.orgIdHeaders = append(cfg.orgIdHeaders, tenancy.DefaultTenantHeader)

	queryRangeCacheConfContentYaml, err := cfg.QueryRangeConfig.CachePathOrContent.Content()
	if err != nil {
		return err
	}
	if len(queryRangeCacheConfContentYaml) > 0 {
		cacheConfig, err := queryfrontend.NewCacheConfig(logger, queryRangeCacheConfContentYaml)
		if err != nil {
			return errors.Wrap(err, "initializing the query range cache config")
		}
		cfg.QueryRangeConfig.ResultsCacheConfig = &queryrange.ResultsCacheConfig{
			Compression:                cfg.CacheCompression,
			CacheConfig:                *cacheConfig,
			CacheQueryableSamplesStats: cfg.CortexHandlerConfig.QueryStatsEnabled,
		}
	}

	labelsCacheConfContentYaml, err := cfg.LabelsConfig.CachePathOrContent.Content()
	if err != nil {
		return err
	}
	if len(labelsCacheConfContentYaml) > 0 {
		cacheConfig, err := queryfrontend.NewCacheConfig(logger, labelsCacheConfContentYaml)
		if err != nil {
			return errors.Wrap(err, "initializing the labels cache config")
		}
		cfg.LabelsConfig.ResultsCacheConfig = &queryrange.ResultsCacheConfig{

View on GitHub (pinned to 35b8b99117)