the `metastore_read_replica` service requires `metastore_rea

Error message

the `metastore_read_replica` service requires `metastore_read_replica_uri` to be set

What it means

A metastore read replica does not store metadata itself; it needs the primary metastore's URI to replicate from. `validate_metastore_read_replica` requires `metastore_read_replica_uri` to be set whenever the `metastore_read_replica` service is enabled, otherwise the node would start with nothing to read from.

Source

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

    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"
    );
    Ok(())
}

/// A list of all the known disk budgets
///

View on GitHub (pinned to a39730c5cd)

Solutions

Set `metastore_read_replica_uri` in the node config to the gRPC URI of the primary metastore.
Export the env variable that resolves the URI (check the env var name in the config template) on the replica node.
If no primary metastore URI exists yet, deploy the primary metastore first and disable the replica service until it is reachable.

Example fix

// before (quickwit.yaml)
services: [metastore_read_replica]
# metastore_read_replica_uri missing

// after (quickwit.yaml)
services: [metastore_read_replica]
metastore_read_replica_uri: http://metastore-primary:7196

Defensive patterns

Strategy: validation

Validate before calling

if config.enabled_services.contains(&QuickwitService::MetastoreReadReplica)
    && config.metastore_read_replica_uri.is_none() {
    return Err("metastore_read_replica enabled but metastore_read_replica_uri not set");
}

Type guard

fn read_replica_configured(cfg: &NodeConfig) -> bool {
    cfg.metastore_read_replica_uri.as_deref().map(|u| !u.is_empty()).unwrap_or(false)
}

Try / catch

match load_node_config(path) {
    Err(e) if e.to_string().contains("metastore_read_replica_uri") =>
        bail!("set metastore_read_replica_uri before enabling the replica service"),
    other => other,
}

Prevention

Always pair the replica service with its URI in config templates.
Verify the URI env var is exported on replica nodes (deployment checklist).
Smoke-test config load right after provisioning, not at first traffic.

When it happens

Trigger: Enabling the `metastore_read_replica` service in the node config while leaving `metastore_read_replica_uri` unset (or env resolution yields none), failing validate at config load.

Common situations: Operators enable the replica service but forget the companion URI setting; the URI is expected from an env var that was never exported on the replica node.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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