jaegertracing/jaeger · error

attribute_metadata_cache_max_size must be a non-negative num

Error message

attribute_metadata_cache_max_size must be a non-negative number

What it means

ClickHouse Configuration.Validate returns this error when AttributeMetadataCacheMaxSize is negative. The cache max size bounds how many attribute metadata entries are cached and cannot be negative.

Source

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

	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

1. Set attribute_metadata_cache_max_size to a non-negative number
2. Replace -1 with an appropriate positive size (the option does not use -1 as a "disabled" sentinel)
3. Add Validate to the startup path so the bad value fails fast

Example fix

// before
attribute_metadata_cache_max_size: -1
// after
attribute_metadata_cache_max_size: 10000

if cfg.AttributeMetadataCacheMaxSize < 0 {
    return errors.New("attribute_metadata_cache_max_size must be a non-negative number")
}

func nonNegativeSize(n int) bool { return n >= 0 }

if err := cfg.Validate(); err != nil {
    if strings.Contains(err.Error(), "attribute_metadata_cache_max_size must be a non-negative number") {
        cfg.AttributeMetadataCacheMaxSize = 10000
    }
}

When it happens

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

Common situations: Negative numbers in config files from typos; computing size from a formula that underflows; misreading the option as a boolean/disabled flag and using -1.

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

• attribute_metadata_cache_ttl must be a non-negative duration
• ttl must be a non-negative duration
• ttl must be a whole number of seconds
• default_search_depth must be a positive number
• max_search_depth must be a positive number

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/406449c227060124. Report an issue: GitHub.