zeroclaw-labs/zeroclaw · warning · DiagItem

embedding route with empty hint

Error message

embedding route with empty hint

What it means

The empty-hint check applied to `embedding_routes`, using `trim()` so whitespace-only hints are caught too. An embedding route without a usable hint cannot be selected, so doctor warns about it during config semantic checks.

Source

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

                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() {
            items.push(DiagItem::warn(cat, "embedding route with empty hint"));
        }
        if let Some(reason) = embedding_provider_validation_error(&route.model_provider) {
            items.push(DiagItem::warn(
                cat,
                format!(
                    "embedding route \"{}\" uses invalid model_provider \"{}\": {}",
                    route.hint, route.model_provider, reason
                ),
            ));
        }
        if route.model.trim().is_empty() {
            items.push(DiagItem::warn(
                cat,
                format!("embedding route \"{}\" has empty model", route.hint),
            ));
        }
        if route.dimensions.is_some_and(|value| value == 0) {
            items.push(DiagItem::warn(

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Set a non-empty (non-whitespace) hint on the embedding route
2. Or remove the unused route entry
3. Re-run `zeroclaw doctor` to confirm embedding route checks pass

Example fix

# before
[[embedding_routes]]
hint = "   "
model_provider = "openai"

# after
[[embedding_routes]]
hint = "docs"
model_provider = "openai"

fn validate_embedding_routes(cfg: &Config) -> Vec<String> {
    cfg.embedding_routes
        .iter()
        .filter(|r| r.hint.trim().is_empty())
        .map(|r| "embedding route with empty hint".to_string())
        .collect()
}

When it happens

Trigger: An `[[embedding_routes]]` entry with `hint = ""`, `hint = " "`, or the field missing; doctor prints `embedding route with empty hint`.

Common situations: Embedding route tables added by copy-paste with placeholder hints; whitespace introduced during templating.

Related errors

• embedding route "{}" uses invalid model_provider "{}": {}
• model route with empty hint
• model route "{}" uses invalid model_provider "{}": {}
• agent "{name}" uses invalid model_provider "{provider_ref}":
• 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/be321da69c0079e9. Report an issue: GitHub.