{"record":{"id":"946079317407c5e6","repo":"zeroclaw-labs/zeroclaw","slug":"needs-quickstart-gateway-booted-without-a-working","errorCode":null,"errorMessage":"needs_quickstart: gateway booted without a working model_provider. Complete browser quickstart at /quickstart, or fix [providers.models.<type>.<alias>] and POST /admin/reload.","messagePattern":"needs_quickstart: gateway booted without a working model_provider\\. Complete browser quickstart at /quickstart, or fix \\[providers\\.models\\.<type>\\.<alias>\\] and POST /admin/reload\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-gateway/src/lib.rs","lineNumber":2416,"sourceCode":"}\n\n/// Result of a gateway chat turn.\nstruct GatewayChatOutcome {\n    response: String,\n}\n\nstruct UnconfiguredModelProvider;\n\n#[async_trait::async_trait]\nimpl ModelProvider for UnconfiguredModelProvider {\n    async fn chat_with_system(\n        &self,\n        _system_prompt: Option<&str>,\n        _message: &str,\n        _model: &str,\n        _temperature: Option<f64>,\n    ) -> anyhow::Result<String> {\n        anyhow::bail!(\n            \"needs_quickstart: gateway booted without a working model_provider. \\\n             Complete browser quickstart at /quickstart, or fix \\\n             [providers.models.<type>.<alias>] and POST /admin/reload.\"\n        )\n    }\n}\n\nimpl ::zeroclaw_api::attribution::Attributable for UnconfiguredModelProvider {\n    fn role(&self) -> ::zeroclaw_api::attribution::Role {\n        ::zeroclaw_api::attribution::Role::Provider(\n            ::zeroclaw_api::attribution::ProviderKind::Model(\n                ::zeroclaw_api::attribution::ModelProviderKind::Custom,\n            ),\n        )\n    }\n    fn alias(&self) -> &str {\n        \"unconfigured\"\n    }","sourceCodeStart":2398,"sourceCodeEnd":2434,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-gateway/src/lib.rs#L2398-L2434","documentation":"The gateway boots with an `UnconfiguredModelProvider` placeholder when no usable model provider could be built from configuration. Every `chat_with_system` call on that placeholder bails with `needs_quickstart`, directing the operator to the browser quickstart at `/quickstart` or to fix the `[providers.models.<type>.<alias>]` config section and then `POST /admin/reload`. It means the gateway process is healthy but has no LLM backend wired.","triggerScenarios":"Fresh install with no provider configured; a `[providers.models...]` entry that failed to build (bad API key, unknown provider type); any chat request routed to the gateway before a working provider exists.","commonSituations":"First boot before completing browser quickstart; editing config.toml with a schema or syntax error that makes provider construction fall back to the placeholder; renaming or deleting a model alias while channels still reference it.","solutions":["Open the gateway's `/quickstart` page in a browser and complete provider setup","Fix or add `[providers.models.<type>.<alias>]` in config.toml, then `POST /admin/reload` (no restart needed)","Check gateway startup logs for why the configured provider failed to build, fix that root cause, then reload"],"exampleFix":"# before — config.toml has no provider section\n# after\n[providers.models.openai.gpt-4o-mini]\napi_key = \"sk-your-key\"\n# then: curl -X POST http://127.0.0.1:8080/admin/reload","handlingStrategy":"try-catch","validationCode":"// Before wiring channels that will chat, smoke-test the provider:\nif let Err(e) = gateway.chat_with_system(None, \"ping\", &default_model, None).await {\n    if e.to_string().starts_with(\"needs_quickstart\") {\n        eprintln!(\"complete /quickstart or fix [providers.models.*] before use\");\n    }\n    return Err(e);\n}","typeGuard":null,"tryCatchPattern":"match provider.chat_with_system(None, msg, model, temp).await {\n    Err(e) if e.to_string().starts_with(\"needs_quickstart\") => {\n        // Configuration problem, not a transient failure: direct the user to setup.\n        return Ok(render_setup_required_response());\n    }\n    other => other,\n}","preventionTips":["Complete /quickstart before connecting channels that trigger chat","After every config.toml provider edit, POST /admin/reload and run a one-message smoke test","Watch gateway boot logs for provider-construction failures that fall back to the placeholder"],"tags":["gateway","configuration","quickstart","model-provider"],"backgroundTag":"missing-configuration","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}