zeroclaw-labs/zeroclaw · warning · DiagItem

model route with empty hint

Error message

model route with empty hint

What it means

Requests select a model route by matching its `hint`; a `[[model_routes]]` entry with an empty hint can never match anything useful. Doctor flags it during config semantic checks as a dead or misdefined route.

Source

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

            }
        }
        if !found_any {
            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),
            ));
        }
    }

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Give the route a non-empty hint string that requests can actually match
2. Or remove the dead route entry from the config
3. Re-run `zeroclaw doctor` to confirm route checks pass

Example fix

# before
[[model_routes]]
hint = ""
model = "gpt-4o-mini"

# after
[[model_routes]]
hint = "cheap"
model = "gpt-4o-mini"

fn validate_model_routes(cfg: &Config) -> Vec<String> {
    cfg.model_routes
        .iter()
        .filter(|r| r.hint.is_empty() || r.model.is_empty())
        .map(|r| format!("route incomplete: {r:?}"))
        .collect()
}
// deploy only when the returned Vec is empty

When it happens

Trigger: A model_routes entry with `hint = ""` or a missing hint key; `zeroclaw doctor` prints `model route with empty hint`.

Common situations: Route tables drafted with placeholders; hint fields dropped during hand-editing or templating.

Related errors

• model route "{}" uses invalid model_provider "{}": {}
• model route "{}" has empty model
• embedding route with empty hint
• embedding route "{}" uses invalid model_provider "{}": {}
• agent "{name}" uses invalid model_provider "{provider_ref}":

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