{"record":{"id":"6489b5c2338cf1d0","repo":"quickwit-oss/quickwit","slug":"the-metastore-read-replica-service-requires-met","errorCode":null,"errorMessage":"the `metastore_read_replica` service requires `metastore_read_replica_uri` to be set","messagePattern":"the `metastore_read_replica` service requires `metastore_read_replica_uri` to be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"quickwit/quickwit-config/src/node_config/serialize.rs","lineNumber":438,"sourceCode":"    validate_disk_usage(node_config);\n    Ok(())\n}\n\n/// Validates the configuration of the [`QuickwitService::MetastoreReadReplica`] role and searcher\n/// read-replica routing.\n///\n/// The [`QuickwitService::MetastoreReadReplica`] role serves the same gRPC service as a read-only\n/// metastore, so it must run standalone and requires `metastore_read_replica_uri` to connect to.\nfn validate_metastore_read_replica(node_config: &NodeConfig) -> anyhow::Result<()> {\n    let read_replica_enabled =\n        node_config.is_service_enabled(QuickwitService::MetastoreReadReplica);\n    if read_replica_enabled {\n        ensure!(\n            node_config.enabled_services.len() == 1,\n            \"the `metastore_read_replica` service must run standalone and cannot be combined with \\\n             any other service\"\n        );\n        ensure!(\n            node_config.metastore_read_replica_uri.is_some(),\n            \"the `metastore_read_replica` service requires `metastore_read_replica_uri` to be set\"\n        );\n    }\n    let searcher_uses_read_replica = node_config.is_service_enabled(QuickwitService::Searcher)\n        && node_config.searcher_config.use_metastore_read_replica;\n    // Avoid a deadlock where the searcher waits for a READY read replica, while the read\n    // replica waits for this primary metastore to become READY.\n    ensure!(\n        !(searcher_uses_read_replica && node_config.is_service_enabled(QuickwitService::Metastore)),\n        \"`searcher.use_metastore_read_replica` cannot be enabled on a node running the \\\n         `metastore` service\"\n    );\n    Ok(())\n}\n\n/// A list of all the known disk budgets\n///","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-config/src/node_config/serialize.rs#L420-L456","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (quickwit.yaml)\nservices: [metastore_read_replica]\n# metastore_read_replica_uri missing\n\n// after (quickwit.yaml)\nservices: [metastore_read_replica]\nmetastore_read_replica_uri: http://metastore-primary:7196","handlingStrategy":"validation","validationCode":"if config.enabled_services.contains(&QuickwitService::MetastoreReadReplica)\n    && config.metastore_read_replica_uri.is_none() {\n    return Err(\"metastore_read_replica enabled but metastore_read_replica_uri not set\");\n}","typeGuard":"fn read_replica_configured(cfg: &NodeConfig) -> bool {\n    cfg.metastore_read_replica_uri.as_deref().map(|u| !u.is_empty()).unwrap_or(false)\n}","tryCatchPattern":"match load_node_config(path) {\n    Err(e) if e.to_string().contains(\"metastore_read_replica_uri\") =>\n        bail!(\"set metastore_read_replica_uri before enabling the replica service\"),\n    other => other,\n}","preventionTips":["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."],"tags":["config","validation","metastore","missing-setting"],"backgroundTag":"missing-required-config-field","analyzedSha":"a39730c5cdcd1a4fe798403737ae293999ea21f8","analyzedAt":"2026-09-08T13:19:37.784Z","contentChangedAt":"2026-09-08T13:19:37.784Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}