quickwit-oss/quickwit · error

the `metastore_read_replica` service must run standalone and

Error message

the `metastore_read_replica` service must run standalone and cannot be combined with any other service

What it means

The `metastore_read_replica` role serves the same gRPC service as a read-only metastore and therefore must be the only service enabled on the node. `validate_metastore_read_replica` (called from validate) rejects any config where it is combined with other services, because co-hosted roles would conflict with the read-replica's readiness semantics.

Source

Thrown at quickwit/quickwit-config/src/node_config/serialize.rs:433

            "the `compactor` service can only be enabled when `enable_standalone_compactors` is \
             true (or `QW_ENABLE_STANDALONE_COMPACTORS=true`). With the default indexer-local \
             merge pipeline, the compactor service must not be enabled."
        );
    }
    validate_disk_usage(node_config);
    Ok(())
}

/// Validates the configuration of the [`QuickwitService::MetastoreReadReplica`] role and searcher
/// read-replica routing.
///
/// The [`QuickwitService::MetastoreReadReplica`] role serves the same gRPC service as a read-only
/// metastore, so it must run standalone and requires `metastore_read_replica_uri` to connect to.
fn validate_metastore_read_replica(node_config: &NodeConfig) -> anyhow::Result<()> {
    let read_replica_enabled =
        node_config.is_service_enabled(QuickwitService::MetastoreReadReplica);
    if read_replica_enabled {
        ensure!(
            node_config.enabled_services.len() == 1,
            "the `metastore_read_replica` service must run standalone and cannot be combined with \
             any other service"
        );
        ensure!(
            node_config.metastore_read_replica_uri.is_some(),
            "the `metastore_read_replica` service requires `metastore_read_replica_uri` to be set"
        );
    }
    let searcher_uses_read_replica = node_config.is_service_enabled(QuickwitService::Searcher)
        && node_config.searcher_config.use_metastore_read_replica;
    // Avoid a deadlock where the searcher waits for a READY read replica, while the read
    // replica waits for this primary metastore to become READY.
    ensure!(
        !(searcher_uses_read_replica && node_config.is_service_enabled(QuickwitService::Metastore)),
        "`searcher.use_metastore_read_replica` cannot be enabled on a node running the \
         `metastore` service"
    );

View on GitHub (pinned to a39730c5cd)

Solutions

1. Run the metastore_read_replica on its own node: remove every other service from its `services` list.
2. If you need those other roles, deploy them on separate nodes with their own configs.
3. If a read-only metastore is not actually needed, remove `metastore_read_replica` from the services list entirely.

Example fix

// before (quickwit.yaml)
services: [searcher, metastore_read_replica]

// after (quickwit.yaml)
services: [metastore_read_replica]
# searcher runs on a separate node

let enabled: &[QuickwitService] = &config.enabled_services;
if enabled.contains(&QuickwitService::MetastoreReadReplica) {
    assert_eq!(enabled.len(), 1, "metastore_read_replica must run standalone");
}

fn is_standalone_read_replica(services: &[QuickwitService]) -> bool {
    !services.contains(&QuickwitService::MetastoreReadReplica) || services.len() == 1
}

if let Err(e) = load_node_config(path) {
    if e.to_string().contains("metastore_read_replica") {
        eprintln!("Split metastore_read_replica onto its own node: {e}");
    }
    return Err(e);
}

When it happens

Trigger: Enabling `metastore_read_replica` together with any other service (searcher, indexer, metastore, etc.) in the node's `services` list, then loading the node config through validate.

Common situations: Operators try to consolidate roles on small clusters and list metastore_read_replica alongside searcher or indexer; templates from all-in-one nodes are edited by adding the replica service.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• {left:?} metastore config is defined multiple times
• the `metastore_read_replica` service requires `metastore_rea
• `searcher.use_metastore_read_replica` cannot be enabled on a
• index ID pattern `{pattern}` is invalid: patterns must not c
• index ID pattern `{pattern}` is invalid: an index ID must ha

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/7f7fd05ece5b3739. Report an issue: GitHub.