zeroclaw-labs/zeroclaw · warning

model route "{}" uses invalid model_provider "{}": {}

Error message

model route "{}" uses invalid model_provider "{}": {}

What it means

`zeroclaw doctor` semantic check walks `model_routes` and tries to instantiate each route's `model_provider` through `create_doctor_model_provider`. When the name does not resolve to a usable provider slot, doctor emits this warning naming the route hint, the offending provider ref, and the first line of the underlying error. It is a diagnostic warning, not a crash.

Source

Thrown at crates/zeroclaw-runtime/src/doctor/mod.rs:1248

            items.push(DiagItem::error(cat, "no model providers configured"));
        }
    }

    // Gateway port range
    let port = config.gateway.port;
    if port > 0 {
        items.push(DiagItem::ok(cat, format!("gateway port: {port}")));
    } else {
        items.push(DiagItem::error(cat, "gateway port is 0 (invalid)"));
    }

    // Model routes validation
    for route in &config.model_routes {
        if route.hint.is_empty() {
            items.push(DiagItem::warn(cat, "model route with empty hint"));
        }
        if let Some(reason) = provider_validation_error(config, &route.model_provider) {
            items.push(DiagItem::warn(
                cat,
                format!(
                    "model route \"{}\" uses invalid model_provider \"{}\": {}",
                    route.hint, route.model_provider, reason
                ),
            ));
        }
        if route.model.is_empty() {
            items.push(DiagItem::warn(
                cat,
                format!("model route \"{}\" has empty model", route.hint),
            ));
        }
    }

    // Embedding routes validation
    for route in &config.embedding_routes {
        if route.hint.trim().is_empty() {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Point the route's `model_provider` at an existing provider key from the config's providers table
2. If the provider is genuinely missing, add the provider slot the route needs
3. Re-run `zeroclaw doctor` and confirm the warning clears

Example fix

# before
[[model_routes]]
hint = "cheap"
model_provider = "openai-mini"   # no such provider

# after
[[model_routes]]
hint = "cheap"
model_provider = "openai"        # matches [providers.openai]

let out = std::process::Command::new("zeroclaw")
    .args(["doctor"])
    .output()?;
let text = String::from_utf8_lossy(&out.stdout);
if text.contains("uses invalid model_provider") {
    return Err(anyhow::anyhow!("config has invalid model_provider refs; fix routes before deploy"));
}

When it happens

Trigger: A `[[model_routes]]` entry whose `model_provider` references a key that is not defined in the providers table (or whose slot is itself invalid); running `zeroclaw doctor` -> check_config_semantics prints the warning.

Common situations: Typos in provider names; a provider slot renamed or deleted without updating routes; configs assembled from templates whose route/provider names do not match.

Related errors

• embedding route "{}" uses invalid model_provider "{}": {}
• agent "{name}" uses invalid model_provider "{provider_ref}":
• model route with empty hint
• model route "{}" has empty model
• config section `{$path}` is malformed and was reset to defau

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