{"record":{"id":"82058b16d71273e8","repo":"quickwit-oss/quickwit","slug":"metastore-read-replica-uri-must-be-set-when-the","errorCode":null,"errorMessage":"`metastore_read_replica_uri` must be set when the `metastore_read_replica` role is enabled","messagePattern":"`metastore_read_replica_uri` must be set when the `metastore_read_replica` role is enabled","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"quickwit/quickwit-serve/src/metastore.rs","lineNumber":255,"sourceCode":"        let metastore = MetastoreServiceClient::tower()\n            .stack_layer(shared_layer)\n            .stack_create_index_layer(broker_layer.clone())\n            .stack_delete_index_layer(broker_layer.clone())\n            .stack_add_source_layer(broker_layer.clone())\n            .stack_delete_source_layer(broker_layer.clone())\n            .stack_toggle_source_layer(broker_layer)\n            .build(metastore);\n        return Ok(LocalMetastoreServer::Primary(metastore));\n    }\n    // Instantiate a read-only metastore replica server if the `metastore_read_replica` role is\n    // enabled on the node.\n    if node_config.is_service_enabled(QuickwitService::MetastoreReadReplica) {\n        info!(\n            metastore_kind = \"read_replica\",\n            \"starting local metastore service\"\n        );\n        let Some(read_replica_uri) = &node_config.metastore_read_replica_uri else {\n            bail!(\n                \"`metastore_read_replica_uri` must be set when the `metastore_read_replica` role \\\n                 is enabled\"\n            );\n        };\n        let metastore: MetastoreServiceClient = metastore_resolver\n            .resolve_read_only(read_replica_uri)\n            .await\n            .with_context(|| {\n                format!(\"failed to resolve metastore read replica uri `{read_replica_uri}`\")\n            })?;\n        let shared_layer = ServiceBuilder::new()\n            .layer(READ_REPLICA_METASTORE_GRPC_SERVER_METRICS_LAYER.clone())\n            .layer(LoadShedLayer::new(\n                LocalMetastoreServer::metastore_max_in_flight_requests(\n                    node_config,\n                    read_replica_uri,\n                ),\n            ))","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/quickwit-oss/quickwit/blob/a39730c5cdcd1a4fe798403737ae293999ea21f8/quickwit/quickwit-serve/src/metastore.rs#L237-L273","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set `metastore_read_replica_uri` in the node config to a valid read-only metastore URI (e.g. postgres://...).","If the node should not run a replica, remove the `metastore_read_replica` role from the services list.","Validate the config with `quickwit config check` (or equivalent) before deploying."],"exampleFix":"// before (config)\nservice:\n  - metastore_read_replica\n// after\nservice:\n  - metastore_read_replica\nmetastore_read_replica_uri: postgres://user:pass@postgres:5432/quickwit","handlingStrategy":"validation","validationCode":"if services.contains(\"metastore_read_replica\") && node_config.metastore_read_replica_uri.is_none() {\n    panic!(\"metastore_read_replica_uri must be set when the metastore_read_replica role is enabled\");\n}","typeGuard":"let Some(read_replica_uri) = &node_config.metastore_read_replica_uri else { return Err(/* config error */); };","tryCatchPattern":null,"preventionTips":["Keep role and its required URI adjacent in config templates.","Run config validation at deploy time before starting nodes."],"tags":["config","startup","metastore"],"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-14T11:17:12.474Z"}