{"record":{"id":"9aa38177f93093ab","repo":"zeroclaw-labs/zeroclaw","slug":"fallback-provider-raw-resolved-to-resolved-9aa381","errorCode":null,"errorMessage":"Fallback provider `{raw}` resolved to `{resolved}` ({profile}) failed to build: {e}","messagePattern":"Fallback provider `(.+?)` resolved to `(.+?)` \\((.+?)\\) failed to build: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-providers/src/lib.rs","lineNumber":1582,"sourceCode":"            anyhow::bail!(\n                \"Fallback provider `{raw}` resolved to `{resolved}` ({profile}) but no \\\n                 profile-resolved credential exists. Set `api_key` on {profile}, configure \\\n                 the alias's external auth flow, or remove it from `fallback`.\"\n            );\n        }\n\n        match create_model_provider_inner(\n            Some(config),\n            family,\n            &alias,\n            entry.api_key.as_deref(),\n            entry.uri.as_deref(),\n            &opts,\n        ) {\n            Ok(built) => push_pinned_entries(out, config, family, &alias, built, None),\n            Err(e) => {\n                let profile = format!(\"[providers.models.{family}.{alias}]\");\n                anyhow::bail!(\n                    \"Fallback provider `{raw}` resolved to `{resolved}` ({profile}) failed to \\\n                     build: {e}\"\n                );\n            }\n        }\n\n        visited.push(resolved.clone());\n        append_fallback_chain(out, config, &entry.fallback, visited, depth + 1)?;\n        visited.pop();\n    }\n    Ok(())\n}\n\npub fn create_resilient_model_provider_from_ref(\n    config: &zeroclaw_config::schema::Config,\n    name: &str,\n    api_key: Option<&str>,\n    api_url: Option<&str>,","sourceCodeStart":1564,"sourceCodeEnd":1600,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-providers/src/lib.rs#L1564-L1600","documentation":"The fallback alias passed the auth-readiness check but create_model_provider_inner failed while building the concrete provider; the underlying factory error is chained after the profile name and the resolved alias. Because the chain is built at startup, a broken fallback fails the whole provider construction even though the primary is healthy.","triggerScenarios":"Fallback alias with a malformed uri, invalid per-alias options (e.g. an unsupported wire_api or tuning value), an unknown provider family, or credential data that passes readiness but fails deep validation inside the family factory.","commonSituations":"Editing an alias's settings (uri, options) and breaking its construction while the primary still works; renaming option keys after a ZeroClaw upgrade; fallback aliases pointing at deprecated endpoints.","solutions":["Read the trailing `{e}` chain first — it is the actual cause, not this wrapper message","Reproduce standalone: briefly make the named alias the primary, or list providers, to see the direct error","Check the uri scheme/format and family-specific options on the named profile","If the chained error mentions credentials despite passing readiness, re-run the alias's auth flow"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match build_resilient_from_ref(config, &primary).await {\n    Err(e) if e.to_string().contains(\"failed to build\") => {\n        // unwrap the chain: the trailing cause names the real per-alias problem\n        let cause = e.source().map(|s| s.to_string()).unwrap_or_default();\n        return Err(anyhow::anyhow!(\"fallback build failed: {cause}\"));\n    }\n    other => other,\n}","preventionTips":["Test each alias standalone after changing its uri or options, not just the primary","Read the chained cause before the wrapper text when diagnosing fallback failures","Keep fallback aliases on the same validation path as primaries in config review"],"tags":["fallback","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"}