valeriansaliou/sonic · critical · panic

max_background_jobs makes max_flushes unneeded, don’t config

Error message

max_background_jobs makes max_flushes unneeded, don’t configure both

What it means

Config::validate() panics when both max_flushes and max_background_jobs are set for the KV database. max_background_jobs supersedes max_flushes, so specifying both is contradictory; only one may be configured.

Source

Thrown at core/src/config.rs:50

}

impl Config {
    pub fn validate(&self) {
        // Check 'write_buffer' for KV
        if self.store.kv.database.write_buffer_size == Some(0) {
            panic!("write_buffer for kv must not be zero");
        }

        // Check 'flush_after' for KV
        if self.store.kv.database.flush_after >= self.store.kv.pool.inactive_after {
            panic!("flush_after for kv must be strictly lower than inactive_after");
        }

        // Check 'flush_after' for KV
        if self.store.kv.database.max_flushes.is_some()
            && self.store.kv.database.max_background_jobs.is_some()
        {
            panic!("max_background_jobs makes max_flushes unneeded, don’t configure both");
        }

        // Check 'consolidate_after' for FST
        if self.store.fst.graph.consolidate_after >= self.store.fst.pool.inactive_after {
            panic!("consolidate_after for fst must be strictly lower than inactive_after");
        }
    }
}

/// Configuration group for normalization options (Unicode normalization,
/// stemming, lemmatization…).
#[derive(Deserialize, Clone, Copy)]
pub struct ConfigNormalization {
    #[serde(with = "crate::util::serde::none_string_as_none")]
    pub unicode_normalization: Option<UnicodeNormalization>,

    pub diacritic_folding_enabled: bool,

View on GitHub (pinned to e6a72da6a5)

Solutions

1. Remove max_flushes from [store.kv.database] and keep max_background_jobs
2. Or remove max_background_jobs if you intend to keep legacy max_flushes tuning
3. Restart the server after fixing the config

Example fix

// config.toml
// before
[store.kv.database]
max_flushes = 4
max_background_jobs = 4

// after
[store.kv.database]
max_background_jobs = 4

let kv = &cfg.store.kv.database;
if kv.max_flushes.is_some() && kv.max_background_jobs.is_some() {
    return Err("configure max_background_jobs OR max_flushes, not both".into());
}

When it happens

Trigger: Setting both store.kv.database.max_flushes and store.kv.database.max_background_jobs (both Some(..)) in the config, then starting the server.

Common situations: Upgrading from an older Sonic config that used max_flushes and adding the newer max_background_jobs without removing the old key; copy-pasting a merged example config.

Related errors

• write_buffer for kv must not be zero
• flush_after for kv must be strictly lower than inactive_afte
• consolidate_after for fst must be strictly lower than inacti
• env_var: variable '{key}' is not set
• Cannot find config file at {custom_path:?}

AI-assisted analysis of valeriansaliou/sonic@e6a72da6a5 (2026-09-01). Data as JSON: /api/errors/7b75fa312973d596. Report an issue: GitHub.