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

unknown provider family {family:?}

Error message

unknown provider family {family:?}

What it means

list_models_for_family maps a provider family name to public catalog sources via catalog_source_for (plus special cases nearai and atlascloud). It errors with 'unknown provider family' when the family string matches no entry in that table - the string is not a family ZeroClaw knows how to enumerate.

Source

Thrown at crates/zeroclaw-providers/src/catalog.rs:206

        .await?
        .error_for_status()?;
    let bytes = response.bytes().await?;
    parse_openai_models_catalog(&bytes)
}

/// Probe the catalog for `family` without constructing a live provider.
/// Returns the union of every known public catalog source. Errors if
/// `family` is unknown or has no public catalog source set.
pub async fn list_models_for_family(family: &str) -> Result<Vec<String>> {
    if family == "nearai" {
        return list_nearai_models().await;
    }
    if family == "atlascloud" {
        return list_atlascloud_models().await;
    }

    let Some((md_key, or_prefix)) = catalog_source_for(family) else {
        anyhow::bail!("unknown provider family {family:?}");
    };
    if let Some(k) = md_key
        && let Ok(ms) = crate::models_dev::list_models_for(k).await
        && !ms.is_empty()
    {
        return Ok(ms);
    }
    if let Some(p) = or_prefix {
        return crate::openrouter_catalog::list_models_for_vendor(p).await;
    }
    anyhow::bail!("no public catalog for family {family:?}")
}

#[must_use]
pub fn sort_model_catalog_for_chat(provider: &str, models: Vec<String>) -> Option<Vec<String>> {
    let provider_l = provider.to_ascii_lowercase();
    let mut ranked: Vec<(i32, String, String)> = models
        .into_iter()

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Use one of the family keys listed in catalog_source_for in crates/zeroclaw-providers/src/catalog.rs (openai, anthropic, azure, bedrock, gemini, gemini_cli, grok_cli, openrouter, copilot, xai, and others) - lowercase and exact
2. For custom OpenAI-compatible endpoints use the compatible family with base_url, not an invented family name
3. Upgrade zeroclaw-providers if the config targets a family added in a newer release
4. Double-check spelling, e.g. "gemini_cli" not "Gemini CLI"

Example fix

# before (config)
[model_provider.my-provider]
family = "openai-compatible"
base_url = "https://api.example.com/v1"

# after
[model_provider.my-provider]
family = "compatible"
base_url = "https://api.example.com/v1"

// Check the family is catalog-known before calling
let family = family.trim().to_ascii_lowercase();
if family != "nearai"
    && family != "atlascloud"
    && zeroclaw_providers::catalog::catalog_source_for(&family).is_none()
{
    anyhow::bail!("family {family:?} has no model catalog; check spelling");
}
let models = zeroclaw_providers::catalog::list_models_for_family(&family).await?;

match list_models_for_family(&family).await {
    Ok(models) => { /* ... */ }
    Err(e) if e.to_string().contains("unknown provider family") => {
        // fall back to a configured static model list for this alias
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling list_models_for_family with a typo'd or unregistered family string (e.g. "openai-compatible", "open-ai", "Gemini CLI"), passing a provider alias instead of a family name, or a config written for a newer release that added a family the installed binary does not know.

Common situations: Typos in model_provider family config; configs authored against a newer ZeroClaw release than the installed binary; custom OpenAI-compatible endpoints given an invented family instead of using the compatible family.

Related errors

• matrix: configure either `access_token` or `password`
• Nextcloud Talk: no bot secret configured (set bot_token or w
• model_provider `{family}` has multiple configured aliases; u
• Unsupported auth profile kind: {other}
• no public catalog for family {family:?}

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