thanos-io/thanos · error

parsing config YAML file

Error message

parsing config YAML file

What it means

NewCachingBucketFromYaml parses the user-supplied YAML caching-bucket configuration with yaml.UnmarshalStrict into CachingWithBackendConfig; any parse error (unknown fields due to strict mode, bad types, malformed YAML) is wrapped as 'parsing config YAML file'. The library throws it because a valid config struct is required before a cache can be constructed.

Solutions

1. Validate the YAML with a YAML linter and against the CachingWithBackendConfig schema
2. Remove or correct unknown keys — strict unmarshalling rejects unrecognized fields
3. Check the Thanos version's docs for current field names and types (renames happen across releases)
4. Compare against a known-good config from the Thanos repository docs (caching_bucket.md)
5. Fix the reported line: the wrapped error names the exact YAML problem

Example fix

// before
config:
  caches:
    chunks:
      maxsize: 500MB        # wrong: unknown field + wrong type
// after
config:
  caches:
    chunks:
      max_size: 500MB
      max_size_items: 0

var probe map[string]interface{}
if err := yaml.Unmarshal(yamlContent, &probe); err != nil { return fmt.Errorf("invalid caching bucket YAML: %w", err) }

cb, err := storecache.NewCachingBucketFromYaml(yamlContent, logger, reg, bucket, router)
if err != nil {
    if strings.Contains(err.Error(), "parsing config YAML file") {
        return fmt.Errorf("caching bucket config invalid, check unknown keys and types: %w", err)
    }
    return err
}

When it happens

Trigger: Calling NewCachingBucketFromYaml with YAML content that is syntactically invalid, contains unknown keys (strict unmarshalling), or has values of the wrong type (e.g. duration strings, enum values).

Common situations: Typos in Thanos store-gateway caching config keys, missing indentation in the embedded YAML, using deprecated or renamed fields after a Thanos upgrade, or passing flag-joined YAML that does not parse.

Related errors

• parsing http config YAML
• unable to parse objstore config
• unable to unmarshal config content
• query configuration
• failed to parse remote write config

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

Appendix: source

Thrown at pkg/store/cache/caching_bucket_factory.go:84

	cfg.ChunkObjectAttrsTTL = 24 * time.Hour
	cfg.ChunkSubrangeTTL = 24 * time.Hour
	cfg.MaxChunksGetRangeRequests = 3
	cfg.BlocksIterTTL = 5 * time.Minute
	cfg.MetafileExistsTTL = 2 * time.Hour
	cfg.MetafileDoesntExistTTL = 15 * time.Minute
	cfg.MetafileContentTTL = 24 * time.Hour
	cfg.MetafileMaxSize = 1024 * 1024 // Equal to default MaxItemSize in memcached client.
}

// NewCachingBucketFromYaml uses YAML configuration to create new caching bucket.
func NewCachingBucketFromYaml(yamlContent []byte, bucket objstore.Bucket, logger log.Logger, reg prometheus.Registerer, r *route.Router, configPath string) (objstore.InstrumentedBucket, error) {
	level.Info(logger).Log("msg", "loading caching bucket configuration")

	config := &CachingWithBackendConfig{}
	config.Defaults()

	if err := yaml.UnmarshalStrict(yamlContent, config); err != nil {
		return nil, errors.Wrap(err, "parsing config YAML file")
	}

	// Append the config path to the YAML content. This allows
	// using identical config with multiple instances.
	// TODO(GiedriusS): in the long-term add some kind of "name"
	// identifier for each instance.
	cfgHash := string(fmt.Sprintf("%d", xxhash.Sum64(append(yamlContent, []byte(configPath)...))))

	backendConfig, err := yaml.Marshal(config.BackendConfig)
	if err != nil {
		return nil, errors.Wrap(err, "marshal content of cache backend configuration")
	}

	var c cache.Cache
	cfg := cache.NewCachingBucketConfig()

	// Configure cache paths.
	cfg.CacheAttributes("chunks", nil, isTSDBChunkFile, config.ChunkObjectAttrsTTL)

View on GitHub (pinned to 35b8b99117)