quickwit-oss/quickwit · critical

`metastore_read_replica_uri` must be set when the `metastore

Error message

`metastore_read_replica_uri` must be set when the `metastore_read_replica` role is enabled

What it means

Quickwit supports running the metastore as a read replica, which needs its own connection URI distinct from the primary metastore. When the node config enables the `metastore_read_replica` service role but `metastore_read_replica_uri` is absent, startup of the local metastore service bails immediately. It is a deliberate fail-fast configuration invariant check in `start_metastore_service_if_needed`.

Source

Thrown at quickwit/quickwit-serve/src/metastore.rs:255

        let metastore = MetastoreServiceClient::tower()
            .stack_layer(shared_layer)
            .stack_create_index_layer(broker_layer.clone())
            .stack_delete_index_layer(broker_layer.clone())
            .stack_add_source_layer(broker_layer.clone())
            .stack_delete_source_layer(broker_layer.clone())
            .stack_toggle_source_layer(broker_layer)
            .build(metastore);
        return Ok(LocalMetastoreServer::Primary(metastore));
    }
    // Instantiate a read-only metastore replica server if the `metastore_read_replica` role is
    // enabled on the node.
    if node_config.is_service_enabled(QuickwitService::MetastoreReadReplica) {
        info!(
            metastore_kind = "read_replica",
            "starting local metastore service"
        );
        let Some(read_replica_uri) = &node_config.metastore_read_replica_uri else {
            bail!(
                "`metastore_read_replica_uri` must be set when the `metastore_read_replica` role \
                 is enabled"
            );
        };
        let metastore: MetastoreServiceClient = metastore_resolver
            .resolve_read_only(read_replica_uri)
            .await
            .with_context(|| {
                format!("failed to resolve metastore read replica uri `{read_replica_uri}`")
            })?;
        let shared_layer = ServiceBuilder::new()
            .layer(READ_REPLICA_METASTORE_GRPC_SERVER_METRICS_LAYER.clone())
            .layer(LoadShedLayer::new(
                LocalMetastoreServer::metastore_max_in_flight_requests(
                    node_config,
                    read_replica_uri,
                ),
            ))

View on GitHub (pinned to a39730c5cd)

Solutions

1. Set `metastore_read_replica_uri` in the node config to a valid read-only metastore URI (e.g. postgres://...).
2. If the node should not run a replica, remove the `metastore_read_replica` role from the services list.
3. Validate the config with `quickwit config check` (or equivalent) before deploying.

Example fix

// before (config)
service:
  - metastore_read_replica
// after
service:
  - metastore_read_replica
metastore_read_replica_uri: postgres://user:pass@postgres:5432/quickwit

if services.contains("metastore_read_replica") && node_config.metastore_read_replica_uri.is_none() {
    panic!("metastore_read_replica_uri must be set when the metastore_read_replica role is enabled");
}

let Some(read_replica_uri) = &node_config.metastore_read_replica_uri else { return Err(/* config error */); };

When it happens

Trigger: Starting quickwit serve with `service: [metastore_read_replica]` (or QuickwitService::MetastoreReadReplica enabled) in the node config while the `metastore.read_replica.uri` / `metastore_read_replica_uri` field is unset or empty.

Common situations: Operators enabling the read-replica role in a config file but forgetting the companion URI; copy-pasting a primary-metastore node config and stripping the URI; templated configs where the URI variable renders empty.

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

• failed to render config file template: environment variable
• failed to create {index_name} index: {error}
• {left:?} metastore config is defined multiple times
• the `metastore_read_replica` service must run standalone and
• the `metastore_read_replica` service requires `metastore_rea

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