zeroclaw-labs/zeroclaw · warning · DiagItem

memory.embedding_model uses hint "{hint}" but no matching [[

Error message

memory.embedding_model uses hint "{hint}" but no matching [[embedding_routes]] entry exists

What it means

A `zeroclaw doctor` warning from `check_config_semantics`: `memory.embedding_model` holds a non-empty hint string, but no `[[embedding_routes]]` entry has a matching `hint` (compared after trimming). The hint is meant to point at a route by name; with no match, memory cannot resolve which embedding route to use and would fall back or fail at runtime.

Source

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

                    "embedding route \"{}\" has invalid dimensions=0",
                    route.hint
                ),
            ));
        }
    }

    if let Some(hint) = config
        .memory
        .embedding_model
        .strip_prefix("hint:")
        .map(str::trim)
        .filter(|value| !value.is_empty())
        && !config
            .embedding_routes
            .iter()
            .any(|route| route.hint.trim() == hint)
    {
        items.push(DiagItem::warn(
                cat,
                format!(
                    "memory.embedding_model uses hint \"{hint}\" but no matching [[embedding_routes]] entry exists"
                ),
            ));
    }

    // gateway.web_dist_dir: flag values that rely on shell expansion the
    // gateway does not perform. Parallel check lives in
    // `src/commands/self_test.rs::check_web_dist_dir`; keep the wording
    // and predicate in sync.
    check_web_dist_dir(config, items);

    // Channel: at least one configured
    let cc = &config.channels;
    let has_channel = cc.channels().iter().any(|info| info.configured);

    if has_channel {

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Add an `[[embedding_routes]]` entry whose `hint` exactly matches the value in `memory.embedding_model`.
2. Or correct `memory.embedding_model` to reference an existing route's `hint` (watch for typos and stray whitespace).
3. If you removed embedding routes on purpose, clear `memory.embedding_model` so it is empty rather than dangling.
4. Re-run `zeroclaw doctor` to verify the hint resolves.

Example fix

# before
memory.embedding_model = "openai"   # no route with hint = "openai"

[[embedding_routes]]
hint = "embed-main"
model_provider = "openai"
model = "text-embedding-3-small"

# after
memory.embedding_model = "embed-main"

let hint = config.memory.embedding_model.trim();
if !hint.is_empty() {
    assert!(
        config.embedding_routes.iter().any(|r| r.hint.trim() == hint),
        "no [[embedding_routes]] entry with hint = \"{hint}\""
    );
}

fn hint_resolves(hint: &str, route_hints: &[String]) -> bool {
    hint.trim().is_empty()
        || route_hints.iter().any(|h| h.trim() == hint.trim())
}

When it happens

Trigger: Running `zeroclaw doctor`/`diagnose` when `memory.embedding_model` is set to a short alias (e.g. "openai") while every `[[embedding_routes]]` entry has a different `hint`, or no routes exist at all. Comparison is `route.hint.trim() == hint`.

Common situations: Renaming a route's `hint` without updating `memory.embedding_model`; typos or case differences between the two values; deleting a route but leaving the memory hint pointing at it.

Related errors

• embedding route "{}" has empty model
• embedding route "{}" has invalid dimensions=0
• Embedding API error {status}: {text}
• model route "{}" uses invalid model_provider "{}": {}
• embedding route "{}" uses invalid model_provider "{}": {}

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