quickwit-oss/quickwit · error · anyhow::Error

index config merge policy `max_merge_factor` must be superio

Error message

index config merge policy `max_merge_factor` must be superior or equal to `merge_factor`

What it means

The merge policy config in quickwit-config must satisfy the invariant `max_merge_factor >= merge_factor`: the merge factor is how many segments are merged per merge operation, and the max merge factor caps merge sizes. `MergePolicyConfig::validate` compares the two values for the configured policy (ConstWriteAmplification, StableLog, or default) and bails if the cap is below the factor, since such a configuration is contradictory.

Source

Thrown at quickwit/quickwit-config/src/merge_policy_config.rs:242

}

impl MergePolicyConfig {
    pub fn noop() -> Self {
        MergePolicyConfig::Nop
    }

    pub fn validate(&self) -> anyhow::Result<()> {
        let (merge_factor, max_merge_factor) = match self {
            MergePolicyConfig::Nop => {
                return Ok(());
            }
            MergePolicyConfig::ConstWriteAmplification(config) => {
                (config.merge_factor, config.max_merge_factor)
            }
            MergePolicyConfig::StableLog(config) => (config.merge_factor, config.max_merge_factor),
        };
        if max_merge_factor < merge_factor {
            anyhow::bail!(
                "index config merge policy `max_merge_factor` must be superior or equal to \
                 `merge_factor`"
            );
        }
        Ok(())
    }
}

View on GitHub (pinned to a39730c5cd)

Solutions

Raise `max_merge_factor` to at least `merge_factor` (typical: merge_factor 10, max_merge_factor 12).
If you intended smaller merges, lower `merge_factor` instead so it does not exceed `max_merge_factor`.
Validate the index config locally (`quickwit index create` or config validation) before deploying.

Example fix

// before
merge_policy:
  merge_factor: 10
  max_merge_factor: 8
// after
merge_policy:
  merge_factor: 10
  max_merge_factor: 12

Defensive patterns

Strategy: validation

Validate before calling

fn merge_policy_is_consistent(merge_factor: usize, max_merge_factor: usize) -> bool {
    max_merge_factor >= merge_factor
}

Try / catch

// Rust
if let Err(e) = merge_policy_config.validate() {
    eprintln!("invalid merge policy: {e:#}");
    return Err(e);
}

Prevention

Treat max_merge_factor as merge_factor + headroom (e.g. 10/12), never below it.
When tuning for write amplification, lower merge_factor first, then max_merge_factor.
Validate index configs in CI before rollout.

When it happens

Trigger: Setting `merge_policy.max_merge_factor` lower than `merge_factor` in the index config (e.g. `merge_factor: 10, max_merge_factor: 8`) and running config validation at startup or index creation.

Common situations: Hand-tuning merge settings to reduce write amplification and lowering `max_merge_factor` without noticing `merge_factor`; copying configs between indexes with mismatched values; documentation examples edited piecemeal.

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 quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/4bfd2abbc88ae9e2. Report an issue: GitHub.