What causes "default_search_depth must be a positive number" in jaegertracing/jaeger?

Set default_search_depth to a positive integer (e.g. the maximum plausible trace depth)

default_search_depth must be a positive number

Error message

default_search_depth must be a positive number

What it means

ClickHouse Configuration.Validate returns this error when DefaultSearchDepth is zero or negative. A search depth of zero would make every trace search return nothing and a negative one is meaningless, so both are rejected rather than producing empty results.

Source

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

		AttributeMetadataCacheTTL:     defaultAttributeMetadataCacheTTL,
		AttributeMetadataCacheMaxSize: defaultAttributeMetadataCacheMaxSize,
	}
}

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 default_search_depth to a positive integer (e.g. the maximum plausible trace depth)
Provide defaults at config-load time instead of relying on the zero value
Add a Validate call in your bootstrap path so the error is caught before serving traffic

Example fix

// before
cfg.DefaultSearchDepth = 0
// after
cfg.DefaultSearchDepth = 1000

Defensive patterns

Strategy: validation

Validate before calling

if cfg.DefaultSearchDepth <= 0 {
    return errors.New("default_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(), "default_search_depth must be a positive number") {
        cfg.DefaultSearchDepth = 1000
    }
}

Prevention

Always set DefaultSearchDepth explicitly; never rely on zero values
Provide defaults in the config loader
Run Validate in startup tests

When it happens

Trigger: Creating a ClickHouse reader with DefaultSearchDepth <= 0 in the Configuration, surfaced via Validate.

Common situations: Zero-value Configuration structs passed to the factory without setting required fields; config files missing default_search_depth; code assuming a default of 0 means "unlimited".

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/5cc80b7217407e9d. Report an issue: GitHub.