BerriAI/litellm · error · ValueError

SemanticGuard: invalid custom routes file format in {file_pa

Error message

SemanticGuard: invalid custom routes file format in {file_path}

What it means

Error "SemanticGuard: invalid custom routes file format in {file_path}" thrown in BerriAI/litellm.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py:62

        templates: Final = []
        if os.path.isdir(ROUTE_TEMPLATES_DIR):
            for fname in os.listdir(ROUTE_TEMPLATES_DIR):
                if fname.endswith(".yaml"):
                    templates.append(fname.replace(".yaml", ""))
        return sorted(templates)

    @staticmethod
    def load_custom_routes_file(file_path: str) -> list[dict[str, Any]]:
        """Load custom routes from a YAML file."""
        if not os.path.exists(file_path):
            raise ValueError(f"SemanticGuard: custom routes file not found: {file_path}")
        with open(file_path, "r") as f:
            data: Final = yaml.safe_load(f)
        if isinstance(data, list):
            return data
        if isinstance(data, dict):
            return [data]
        raise ValueError(f"SemanticGuard: invalid custom routes file format in {file_path}")

    @classmethod
    def build_routes(
        cls,
        route_templates: list[str] | None,
        custom_routes_file: str | None,
        custom_routes: list[dict[str, Any]] | None,
        global_threshold: float = DEFAULT_SEMANTIC_GUARD_SIMILARITY_THRESHOLD,
    ) -> list["Route"]:
        """Build semantic-router Route objects from templates + custom config."""
        from semantic_router.routers.base import Route

        routes: Final[list[Route]] = []

        if route_templates:
            for template_name in route_templates:
                template_data = cls.load_builtin_template(template_name)
                threshold = template_data.get("similarity_threshold", global_threshold)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Fix the custom routes file to match the expected schema (list of routes with name and utterances).
2. Validate the YAML/JSON syntax of the routes file.

When it happens

Trigger: Thrown at litellm/proxy/guardrails/guardrail_hooks/semantic_guard/route_loader.py:62 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/91aab325594ca27c. Report an issue: GitHub.