zeroclaw-labs/zeroclaw · warning · DiagItem

embedding route "{}" has invalid dimensions=0

Error message

embedding route "{}" has invalid dimensions=0

What it means

A `zeroclaw doctor` warning from `check_config_semantics`: an `[[embedding_routes]]` entry sets `dimensions = 0`. Zero is not a usable embedding vector size, so any request through that route would produce invalid vectors or be rejected upstream. The check only fires when `dimensions` is explicitly `Some(0)`; omitting the key is valid.

Source

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

            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(
                cat,
                format!(
                    "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()

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Set `dimensions` to the model's real vector size (e.g. 1536 for text-embedding-3-small), or delete the `dimensions` key to let the provider default apply.
2. Never use 0 as a placeholder for optional numeric config; omit the key instead.
3. Re-run `zeroclaw doctor` to confirm the route passes validation.

Example fix

# before
[[embedding_routes]]
hint = "openai"
model = "text-embedding-3-small"
dimensions = 0

# after
[[embedding_routes]]
hint = "openai"
model = "text-embedding-3-small"
dimensions = 1536

for route in &config.embedding_routes {
    if let Some(dims) = route.dimensions {
        assert!(dims > 0, "embedding route \"{}\" dimensions must be > 0", route.hint);
    }
}

fn dimensions_are_valid(dims: Option<u64>) -> bool {
    dims.map_or(true, |d| d > 0)
}

When it happens

Trigger: Running `zeroclaw doctor`/`diagnose` on a config where an `[[embedding_routes]]` table contains `dimensions = 0` (the code checks `route.dimensions.is_some_and(|value| value == 0)`).

Common situations: A template initialized `dimensions = 0` as a placeholder; a numeric field was commented out incorrectly and set to zero; scripted config generation that defaults integer fields to 0 instead of omitting them.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• embedding route "{}" has empty model
• memory.embedding_model uses hint "{hint}" but no matching [[
• config at {} does not deserialize strictly; the resilient lo
• 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/281b7aaceeade91f. Report an issue: GitHub.