zeroclaw-labs/zeroclaw · error · anyhow::Error

Fallback provider `{raw}` resolved to `{resolved}` ({profile

Error message

Fallback provider `{raw}` resolved to `{resolved}` ({profile}) failed to build: {e}

What it means

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.

Source

Thrown at crates/zeroclaw-providers/src/lib.rs:1582

            anyhow::bail!(
                "Fallback provider `{raw}` resolved to `{resolved}` ({profile}) but no \
                 profile-resolved credential exists. Set `api_key` on {profile}, configure \
                 the alias's external auth flow, or remove it from `fallback`."
            );
        }

        match create_model_provider_inner(
            Some(config),
            family,
            &alias,
            entry.api_key.as_deref(),
            entry.uri.as_deref(),
            &opts,
        ) {
            Ok(built) => push_pinned_entries(out, config, family, &alias, built, None),
            Err(e) => {
                let profile = format!("[providers.models.{family}.{alias}]");
                anyhow::bail!(
                    "Fallback provider `{raw}` resolved to `{resolved}` ({profile}) failed to \
                     build: {e}"
                );
            }
        }

        visited.push(resolved.clone());
        append_fallback_chain(out, config, &entry.fallback, visited, depth + 1)?;
        visited.pop();
    }
    Ok(())
}

pub fn create_resilient_model_provider_from_ref(
    config: &zeroclaw_config::schema::Config,
    name: &str,
    api_key: Option<&str>,
    api_url: Option<&str>,

View on GitHub (pinned to 88bb9c8533)

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

Defensive patterns

Strategy: try-catch

Try / catch

match build_resilient_from_ref(config, &primary).await {
    Err(e) if e.to_string().contains("failed to build") => {
        // unwrap the chain: the trailing cause names the real per-alias problem
        let cause = e.source().map(|s| s.to_string()).unwrap_or_default();
        return Err(anyhow::anyhow!("fallback build failed: {cause}"));
    }
    other => other,
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/9aa38177f93093ab. Report an issue: GitHub.