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

model_provider `{ref_or_family}` does not resolve to a confi

Error message

model_provider `{ref_or_family}` does not resolve to a configured provider

What it means

Thrown while resolving the argument of a runtime `/models` switch (resolve_provider_ref_for_runtime_switch). `ModelsCommandResolution::NoAlias` means the input named a valid provider family or a dotted `<family>.<alias>` ref, but `config.providers.models.find(...)` found no configured `[providers.models.<family>.<alias>]` entry — either the dotted pair does not exist, or the family exists but has zero configured aliases. The library refuses to construct a provider without a credentialed alias entry, so the model switch is rejected instead of silently using default credentials.

Source

Thrown at crates/zeroclaw-channels/src/orchestrator/mod.rs:1588

        _ => ModelsCommandResolution::Ambiguous { family, aliases },
    }
}

fn resolve_provider_ref_for_runtime_switch(config: &Config, raw: &str) -> anyhow::Result<String> {
    match resolve_models_command(config, raw) {
        ModelsCommandResolution::Resolved(provider_ref) => Ok(provider_ref),
        ModelsCommandResolution::Ambiguous { family, aliases } => {
            let list = aliases
                .iter()
                .map(|alias| format!("{family}.{alias}"))
                .collect::<Vec<_>>()
                .join(", ");
            anyhow::bail!(
                "model_provider `{family}` has multiple configured aliases; use one of: {list}"
            )
        }
        ModelsCommandResolution::NoAlias(ref_or_family) => {
            anyhow::bail!(
                "model_provider `{ref_or_family}` does not resolve to a configured provider"
            )
        }
        ModelsCommandResolution::Unknown => {
            anyhow::bail!("unknown model_provider `{raw}`")
        }
    }
}

fn resolved_runtime_model_provider_ref(
    config: &Config,
    agent_alias: &str,
) -> anyhow::Result<String> {
    let agent = config
        .agents
        .get(agent_alias)
        .with_context(|| format!("agents.{agent_alias} is not configured"))?;
    let configured = agent.model_provider.trim();

View on GitHub (pinned to 88bb9c8533)

Solutions

Check zeroclaw.toml for the `[providers.models.<family>]` table and confirm at least one alias entry exists under it
Add or fix the alias entry, e.g. `zeroclaw config set providers.models.openai.default.api_key sk-...` so `openai` resolves to `openai.default`
If using a dotted ref, verify both segments: family must match a known provider name and alias must match a configured key exactly (case-sensitive lookup)
After editing config, re-run the `/models` command with the family name or the corrected dotted ref

Example fix

# before (zeroclaw.toml has no model provider section)
/models openai
# error: model_provider `openai` does not resolve to a configured provider

# after
zeroclaw config set providers.models.openai.default.api_key "sk-..."
/models openai   # resolves to openai.default

Defensive patterns

Strategy: validation

Validate before calling

use zeroclaw_channels::orchestrator::resolve_provider_ref_for_runtime_switch;
// Before sending the /models switch, dry-run resolution against the same config:
match resolve_provider_ref_for_runtime_switch(&config, arg) {
    Ok(dotted) => send_models_switch(dotted),
    Err(e) => notify_user(format!("provider switch rejected: {e:#}")),
}

Try / catch

match resolve_provider_ref_for_runtime_switch(&config, raw) {
    Ok(ref_) => { /* apply switch */ }
    Err(err) if err.to_string().contains("does not resolve to a configured provider") => {
        // offer the list of configured [providers.models.<family>.<alias>] pairs
    }
    Err(err) => return Err(err),
}

Prevention

Keep at least one credentialed alias per provider family you intend to switch to
Prefer fully-qualified dotted refs (`openai.default`) in automation over bare family names
Validate the provider table with a config check command after editing zeroclaw.toml

When it happens

Trigger: Sending `/models <arg>` over a channel where the arg is either (a) a dotted ref like `openrouter.main` where no `[providers.models.openrouter.main]` section exists, or (b) a bare family name like `openrouter` that `zeroclaw_providers::list_model_providers()` recognizes but for which `aliases_of(&family)` returns an empty list. Also hit by any caller of `resolve_provider_ref_for_runtime_switch` with such an argument.

Common situations: User sets `model_provider = "openai"` expecting built-in defaults without defining `[providers.models.openai.default]` with an API key; typo in the alias part of a dotted ref (e.g. `openai.defualt`); provider section was renamed or removed from zeroclaw.toml; fresh install where no model provider was ever configured.

Related errors

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