{"record":{"id":"e3e974ea7dc55323","repo":"zeroclaw-labs/zeroclaw","slug":"routed-model-provider-name-failed-to-initializ","errorCode":null,"errorMessage":"Routed model_provider `{name}` failed to initialize: {e}","messagePattern":"Routed model_provider `(.+?)` failed to initialize: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-providers/src/lib.rs","lineNumber":1808,"sourceCode":"        let url = if is_primary { api_url } else { None };\n        let entry_options = if is_primary {\n            options.clone()\n        } else {\n            options_for_provider_ref(config, name, options)\n        };\n\n        match create_resilient_model_provider_from_ref_with_model_override(\n            config,\n            name,\n            key,\n            url,\n            reliability,\n            &entry_options,\n            is_primary.then_some(default_model),\n        ) {\n            Ok(model_provider) => model_providers.push((name.clone(), model_provider)),\n            Err(e) => {\n                anyhow::bail!(\"Routed model_provider `{name}` failed to initialize: {e}\");\n            }\n        }\n    }\n\n    // Build route table\n    let routes: Vec<(String, router::Route)> = model_routes\n        .iter()\n        .map(|r| {\n            (\n                r.hint.clone(),\n                router::Route {\n                    provider_name: r.model_provider.clone(),\n                    model: r.model.clone(),\n                },\n            )\n        })\n        .collect();\n","sourceCodeStart":1790,"sourceCodeEnd":1826,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-providers/src/lib.rs#L1790-L1826","documentation":"When an agent defines model routing, the router constructor builds every distinct provider referenced by the routes plus the primary, each through create_resilient_model_provider_from_ref_with_model_override. Any single failure aborts with the failing provider's name and the chained cause, because a router with a missing leg cannot honor its route table. Credential, URL, and fallback errors (including the two fallback errors above) propagate here.","triggerScenarios":"A route entry `model_provider = \"openai.fast\"` whose alias lacks an api_key; a routed alias with an invalid uri; a routed provider whose own fallback chain fails (errors 774/775 surface as this message); primary healthy but one secondary route broken.","commonSituations":"Adding routing to an existing agent without configuring the newly referenced providers; renaming an alias that routes still reference; CI missing one provider's env var while the others are set.","solutions":["Fix the underlying error in the chained `{e}` for the named provider first","Verify every `model_provider` referenced in routes resolves to a configured, authenticated alias","Set an api_key directly on the route entry or on the alias profile","Temporarily remove the failing route to isolate the construction issue"],"exampleFix":"# before\n[[agents.coder.model_routes]]\nhint = \"fast\"\nmodel_provider = \"openai.quick\"\nmodel = \"gpt-4o-mini\"\n\n# after (api_key set on [providers.models.openai.quick])\n[providers.models.openai.quick]\nmodel = \"gpt-4o-mini\"\napi_key = \"sk-...\"\n\n[[agents.coder.model_routes]]\nhint = \"fast\"\nmodel_provider = \"openai.quick\"\nmodel = \"gpt-4o-mini\"","handlingStrategy":"try-catch","validationCode":"fn route_providers_configured(\n    config: &zeroclaw_config::schema::Config,\n    routes: &[(String, String)], // (model_provider, model)\n) -> Result<(), String> {\n    for (name, _) in routes {\n        match name.split_once('.') {\n            Some((family, alias)) => {\n                let ok = config.providers.models.find(family, alias)\n                    .map(|e| e.api_key.as_deref().map(|k| !k.trim().is_empty()).unwrap_or(false))\n                    .unwrap_or(false);\n                if !ok { return Err(format!(\"route provider {name} lacks credentials\")); }\n            }\n            None => continue,\n        }\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = build_routed(config, primary, routes).await {\n    if e.to_string().contains(\"failed to initialize\") {\n        // extract provider name and chained cause; fix that alias's config\n        return Err(e.context(\"fix the named route provider before starting the agent\"));\n    }\n    return Err(e);\n}","preventionTips":["Validate every routed provider at startup in staging, not just the primary","Set route-level api_key when an alias is shared across environments","Keep route model_provider references in sync with alias renames"],"tags":["router","provider-construction","configuration","startup"],"backgroundTag":"provider-initialization-failed","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}