BerriAI/litellm · error · ValueError

embedding_model is required for semantic keyword matching

Error message

embedding_model is required for semantic keyword matching

What it means

Config guard in the complexity router: semantic keyword matching was requested, which routes utterances via embeddings, but no embedding_model is configured to build the SemanticRouter layer with.

Source

Thrown at litellm/router_strategy/complexity_router/complexity_router.py:1467

        if not matches:
            return None
        return max(matches, key=lambda match: TIER_SEVERITY_ORDER.index(match.tier))

    def _get_or_create_semantic_routelayer(self) -> SemanticRouter:
        """Build (once) a SemanticRouter with one route per tier, utterances = that tier's keywords."""
        if self._semantic_routelayer is not None:
            return self._semantic_routelayer

        from semantic_router.routers import SemanticRouter
        from semantic_router.routers.base import Route

        from litellm.router_strategy.auto_router.litellm_encoder import (
            LiteLLMRouterEncoder,
        )

        embedding_model: Final = self.config.embedding_model
        if embedding_model is None:
            raise ValueError("embedding_model is required for semantic keyword matching")

        rules: Final = self.config.keyword_tier_rules or []
        ordered_tiers: Final = tuple(dict.fromkeys(rule.tier.value for rule in rules))
        routes: Final = [
            Route(
                name=tier,
                utterances=[keyword for rule in rules if rule.tier.value == tier for keyword in rule.keywords],
                score_threshold=self.config.match_threshold,
            )
            for tier in ordered_tiers
        ]
        routelayer: Final = SemanticRouter(
            routes=routes,
            encoder=LiteLLMRouterEncoder(
                litellm_router_instance=self.litellm_router_instance,
                model_name=embedding_model,
                score_threshold=self.config.match_threshold,
            ),

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set embedding_model in the config to enable semantic keyword matching.

When it happens

Trigger: Thrown at litellm/router_strategy/complexity_router/complexity_router.py:1467 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/e0ce74019a6a9846. Report an issue: GitHub.