jaegertracing/jaeger · error
max_search_depth must be a positive number
Error message
max_search_depth must be a positive number
What it means
ClickHouse Configuration.Validate returns this error when MaxSearchDepth is zero or negative. Like DefaultSearchDepth, a non-positive max depth would make trace searches return nothing or be meaningless, so it is rejected up front.
Source
Thrown at internal/storage/v2/clickhouse/config.go:94
}
func (cfg *Configuration) Validate() error {
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 max_search_depth to a positive integer greater than or equal to default_search_depth
- Apply sane defaults when loading configuration
- Run Validate before instantiating the reader so misconfiguration fails fast
Example fix
// before cfg.MaxSearchDepth = 0 // after cfg.MaxSearchDepth = 1000
Defensive patterns
Strategy: validation
Validate before calling
if cfg.MaxSearchDepth <= 0 {
return errors.New("max_search_depth must be a positive number")
} Type guard
func validDepth(n int) bool { return n > 0 } Try / catch
if err := cfg.Validate(); err != nil {
if strings.Contains(err.Error(), "max_search_depth must be a positive number") {
cfg.MaxSearchDepth = 1000
}
} Prevention
- Set MaxSearchDepth >= DefaultSearchDepth when loading config
- Never ship a Configuration struct with unset depth fields
- Include Validate in smoke tests for deployment configs
When it happens
Trigger: Creating a ClickHouse reader with MaxSearchDepth <= 0, typically when the field is left at its zero value in the Configuration.
Common situations: Partial config files omitting max_search_depth; constructing Configuration programmatically without setting it; assuming DefaultSearchDepth alone is sufficient.
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
- default_search_depth must be a positive number
- ttl must be a non-negative duration
- ttl must be a whole number of seconds
- attribute_metadata_cache_ttl must be a non-negative duration
- attribute_metadata_cache_max_size must be a non-negative num
AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01).
Data as JSON: /api/errors/d243aa3232203eb1.
Report an issue: GitHub.