What causes "Routed model_provider `{name}` failed to initialize: {e}" in zeroclaw-labs/zeroclaw?

Fix the underlying error in the chained `{e}` for the named provider first

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

Routed model_provider `{name}` failed to initialize: {e}

Error message

Routed model_provider `{name}` failed to initialize: {e}

What it means

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.

Source

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

        let url = if is_primary { api_url } else { None };
        let entry_options = if is_primary {
            options.clone()
        } else {
            options_for_provider_ref(config, name, options)
        };

        match create_resilient_model_provider_from_ref_with_model_override(
            config,
            name,
            key,
            url,
            reliability,
            &entry_options,
            is_primary.then_some(default_model),
        ) {
            Ok(model_provider) => model_providers.push((name.clone(), model_provider)),
            Err(e) => {
                anyhow::bail!("Routed model_provider `{name}` failed to initialize: {e}");
            }
        }
    }

    // Build route table
    let routes: Vec<(String, router::Route)> = model_routes
        .iter()
        .map(|r| {
            (
                r.hint.clone(),
                router::Route {
                    provider_name: r.model_provider.clone(),
                    model: r.model.clone(),
                },
            )
        })
        .collect();

View on GitHub (pinned to 88bb9c8533)

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

Example fix

# before
[[agents.coder.model_routes]]
hint = "fast"
model_provider = "openai.quick"
model = "gpt-4o-mini"

# after (api_key set on [providers.models.openai.quick])
[providers.models.openai.quick]
model = "gpt-4o-mini"
api_key = "sk-..."

[[agents.coder.model_routes]]
hint = "fast"
model_provider = "openai.quick"
model = "gpt-4o-mini"

Defensive patterns

Strategy: try-catch

Validate before calling

fn route_providers_configured(
    config: &zeroclaw_config::schema::Config,
    routes: &[(String, String)], // (model_provider, model)
) -> Result<(), String> {
    for (name, _) in routes {
        match name.split_once('.') {
            Some((family, alias)) => {
                let ok = config.providers.models.find(family, alias)
                    .map(|e| e.api_key.as_deref().map(|k| !k.trim().is_empty()).unwrap_or(false))
                    .unwrap_or(false);
                if !ok { return Err(format!("route provider {name} lacks credentials")); }
            }
            None => continue,
        }
    }
    Ok(())
}

Try / catch

if let Err(e) = build_routed(config, primary, routes).await {
    if e.to_string().contains("failed to initialize") {
        // extract provider name and chained cause; fix that alias's config
        return Err(e.context("fix the named route provider before starting the agent"));
    }
    return Err(e);
}

Prevention

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

When it happens

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

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

Related errors

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