{"record":{"id":"134f7df2712cef5b","repo":"headroomlabs-ai/headroom","slug":"unknown-backend-backend","errorCode":null,"errorMessage":"Unknown backend: {backend}","messagePattern":"Unknown backend: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/tokenizers/registry.py","lineNumber":299,"sourceCode":"        self,\n        model: str,\n        backend: str | None,\n    ) -> TokenCounter:\n        \"\"\"Create tokenizer for model.\n\n        Args:\n            model: Model name.\n            backend: Backend to use (or None for auto-detect).\n\n        Returns:\n            TokenCounter instance.\n        \"\"\"\n        if backend is None:\n            backend = self._detect_backend(model)\n\n        factory = self._factories.get(backend)\n        if factory is None:\n            raise ValueError(f\"Unknown backend: {backend}\")\n\n        return factory(model)\n\n    def _create_mistral(self, model: str) -> TokenCounter:\n        \"\"\"Create Mistral tokenizer using official mistral-common.\"\"\"\n        try:\n            from .mistral import MistralTokenizer, is_mistral_available\n\n            if is_mistral_available():\n                return MistralTokenizer(model)\n        except ImportError:\n            pass\n\n        logger.warning(\n            \"mistral-common not installed for Mistral tokenizer. \"\n            \"Install with: pip install mistral-common\"\n        )\n        return EstimatingTokenCounter()","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/tokenizers/registry.py#L281-L317","documentation":"TokenizerRegistry._create_tokenizer raises ValueError('Unknown backend: {backend}') when the requested (or auto-detected) backend string has no registered factory in registry._factories. Built-in backends are registered at import; custom ones must be added via register_backend().","triggerScenarios":"get(model, backend='sentencepiece') when no such backend was registered; auto-detection returning a backend name that a trimmed installation never registered; typo in the backend kwarg ('tiktoken ' or 'tik_token').","commonSituations":"Passing backend names copied from other libraries (e.g. LiteLLM provider strings) instead of headroom's backend names; disabling a backend via plugin/config that then gets requested; version upgrades renaming backends.","solutions":["Use a registered backend name (inspect registry._factories keys or the docs) — typically 'tiktoken', 'huggingface', 'estimating', 'mistral'.","Register the custom backend first: TokenizerRegistry.register_backend('mine', factory).","Pass backend=None to rely on auto-detection instead of hardcoding a name."],"exampleFix":"# before\ntok = TokenizerRegistry.get(\"gpt-4o\", backend=\"tik_token\")  # ValueError\n\n# after\ntok = TokenizerRegistry.get(\"gpt-4o\", backend=\"tiktoken\")\n# or auto-detect:\ntok = TokenizerRegistry.get(\"gpt-4o\")","handlingStrategy":"validation","validationCode":"registry = TokenizerRegistry()\nassert backend in registry._factories, f\"backend {backend!r} not registered; known: {sorted(registry._factories)}\"","typeGuard":"def backend_exists(name: str) -> bool:\n    return name in TokenizerRegistry()._factories","tryCatchPattern":"try:\n    tok = TokenizerRegistry.get(model, backend=backend)\nexcept ValueError as e:\n    if \"Unknown backend\" in str(e):\n        tok = TokenizerRegistry.get(model, backend=None)  # auto-detect\n    else:\n        raise","preventionTips":["Let auto-detection pick the backend (backend=None) unless you must pin one.","Register custom backends via register_backend() at startup.","Centralize backend names as constants instead of string literals."],"tags":["registry","backend","api-misuse","typo"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}