attribute_metadata_cache_ttl must be a non-negative duration

Error message

attribute_metadata_cache_ttl must be a non-negative duration

What it means

ClickHouse Configuration.Validate returns this error when AttributeMetadataCacheTTL is negative. The attribute metadata cache TTL controls how long cached attribute metadata lives and must be non-negative.

Source

Thrown at internal/storage/v2/clickhouse/config.go:97

	if _, err := govalidator.ValidateStruct(cfg); err != nil {
		return err
	}
	if cfg.TTL < 0 {
		return errors.New("ttl must be a non-negative duration")
	}
	if cfg.TTL > 0 && cfg.TTL%time.Second != 0 {
		return errors.New("ttl must be a whole number of seconds")
	}
	// A search depth of zero would make every trace search return nothing, and a
	// negative one is meaningless, so reject both rather than querying with them.
	if cfg.DefaultSearchDepth <= 0 {
		return errors.New("default_search_depth must be a positive number")
	}
	if cfg.MaxSearchDepth <= 0 {
		return errors.New("max_search_depth must be a positive number")
	}
	if cfg.AttributeMetadataCacheTTL < 0 {
		return errors.New("attribute_metadata_cache_ttl must be a non-negative duration")
	}
	if cfg.AttributeMetadataCacheMaxSize < 0 {
		return errors.New("attribute_metadata_cache_max_size must be a non-negative number")
	}
	return nil
}

View on GitHub (pinned to 806f444784)

Solutions

Set attribute_metadata_cache_ttl to a non-negative duration
Fix the configuration source so it cannot produce negative durations
Note that unlike main TTL there is no whole-second requirement — only non-negativity is checked

Example fix

// before
attribute_metadata_cache_ttl: -5m
// after
attribute_metadata_cache_ttl: 5m

Defensive patterns

Strategy: validation

Validate before calling

if cfg.AttributeMetadataCacheTTL < 0 {
    return errors.New("attribute_metadata_cache_ttl must be a non-negative duration")
}

Type guard

func nonNegative(d time.Duration) bool { return d >= 0 }

Try / catch

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "attribute_metadata_cache_ttl must be a non-negative duration") {
        cfg.AttributeMetadataCacheTTL = defaultCacheTTL
    }
}

Prevention

Check sign of computed durations before assigning to config
Avoid -1 sentinels for cache TTLs
Validate all cache-related fields together at load time

When it happens

Trigger: Validating a ClickHouse Configuration whose AttributeMetadataCacheTTL is below zero.

Common situations: Negative duration parsed from a YAML/env config; sign error when computing TTL programmatically; copying a value with a leading minus.

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 jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/bbf7a6bfbe381de6. Report an issue: GitHub.