headroomlabs-ai/headroom · error · ValueError

Unknown backend: {backend}

Error message

Unknown backend: {backend}

What it means

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().

Source

Thrown at headroom/tokenizers/registry.py:299

        self,
        model: str,
        backend: str | None,
    ) -> TokenCounter:
        """Create tokenizer for model.

        Args:
            model: Model name.
            backend: Backend to use (or None for auto-detect).

        Returns:
            TokenCounter instance.
        """
        if backend is None:
            backend = self._detect_backend(model)

        factory = self._factories.get(backend)
        if factory is None:
            raise ValueError(f"Unknown backend: {backend}")

        return factory(model)

    def _create_mistral(self, model: str) -> TokenCounter:
        """Create Mistral tokenizer using official mistral-common."""
        try:
            from .mistral import MistralTokenizer, is_mistral_available

            if is_mistral_available():
                return MistralTokenizer(model)
        except ImportError:
            pass

        logger.warning(
            "mistral-common not installed for Mistral tokenizer. "
            "Install with: pip install mistral-common"
        )
        return EstimatingTokenCounter()

View on GitHub (pinned to 322425c43b)

Solutions

1. Use a registered backend name (inspect registry._factories keys or the docs) — typically 'tiktoken', 'huggingface', 'estimating', 'mistral'.
2. Register the custom backend first: TokenizerRegistry.register_backend('mine', factory).
3. Pass backend=None to rely on auto-detection instead of hardcoding a name.

Example fix

# before
tok = TokenizerRegistry.get("gpt-4o", backend="tik_token")  # ValueError

# after
tok = TokenizerRegistry.get("gpt-4o", backend="tiktoken")
# or auto-detect:
tok = TokenizerRegistry.get("gpt-4o")

registry = TokenizerRegistry()
assert backend in registry._factories, f"backend {backend!r} not registered; known: {sorted(registry._factories)}"

def backend_exists(name: str) -> bool:
    return name in TokenizerRegistry()._factories

try:
    tok = TokenizerRegistry.get(model, backend=backend)
except ValueError as e:
    if "Unknown backend" in str(e):
        tok = TokenizerRegistry.get(model, backend=None)  # auto-detect
    else:
        raise

When it happens

Trigger: 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').

Common situations: 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.

Related errors

• unknown Headroom harness config field: {name}
• Must provide either tokenizer or factory
• module {__name__!r} has no attribute {name!r}
• any-llm-sdk is required for AnyLLMBackend. Install with: pip
• {self.name} backend does not support OpenAI format

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/134f7df2712cef5b. Report an issue: GitHub.