headroomlabs-ai/headroom · error · RuntimeError

tiktoken is required for OpenAI provider. Install with: pip

Error message

tiktoken is required for OpenAI provider. Install with: pip install tiktoken

What it means

The cached encoding loader in the OpenAI provider raises RuntimeError when tiktoken is not installed. Token counting for OpenAI models needs a tiktoken encoding; headroom marks tiktoken optional, and this guard fires on the first _get_encoding() call for any model. Note the loader is deliberately bounded and routes through load_encoding so a stalled vocab download raises TiktokenLoadError instead of hanging (GH #956) — but that only applies once tiktoken exists.

Source

Thrown at headroom/providers/openai.py:292

        return (
            f"OpenAI pricing data is {days_old} days old. "
            "Cost estimates may be inaccurate. Verify against actual billing."
        )
    return None


@lru_cache(maxsize=8)
def _get_encoding(encoding_name: str) -> Any:
    """Get tiktoken encoding, cached.

    Routes through the bounded loader so a stalled vocab download raises
    :class:`~headroom.tokenizers.tiktoken_counter.TiktokenLoadError` after a
    timeout instead of hanging the caller indefinitely — ``tiktoken`` fetches
    vocabularies with no network timeout, and this runs on whatever thread
    first counts tokens for a model, including proxy startup (GH #956).
    """
    if not TIKTOKEN_AVAILABLE:
        raise RuntimeError(
            "tiktoken is required for OpenAI provider. Install with: pip install tiktoken"
        )
    from ..tokenizers.tiktoken_counter import load_encoding

    return load_encoding(encoding_name)


def _lookup_encoding_name(model: str, custom_encodings: dict[str, str] | None = None) -> str | None:
    """Resolve the tiktoken encoding for ``model``, or ``None`` if none claims it.

    ``None`` is the "not an OpenAI model" signal: it means no explicit mapping,
    no known prefix, and no OpenAI family pattern matched. Callers that can
    reach a better tokenizer should use it rather than guess an encoding.
    """
    # Check custom encodings first
    if custom_encodings and model in custom_encodings:
        return custom_encodings[model]

View on GitHub (pinned to 322425c43b)

Solutions

Install tiktoken in the environment that runs headroom: pip install tiktoken
Verify with: python -c "import tiktoken" to rule out a broken install or version conflict.
If you cannot install it, disable token-count-dependent features (compression/context sizing) for OpenAI models or use a provider whose tokenizer is available.

Example fix

# before
n = provider.count_tokens("gpt-4o", text)  # RuntimeError: tiktoken is required...

# after (shell)
# pip install tiktoken
n = provider.count_tokens("gpt-4o", text)  # ok

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

tiktoken_ready = importlib.util.find_spec("tiktoken") is not None

Type guard

def tiktoken_available() -> bool:
    return importlib.util.find_spec("tiktoken") is not None

Try / catch

try:
    enc = _get_encoding(encoding_name)
except RuntimeError as exc:
    if "pip install tiktoken" in str(exc):
        raise SystemExit("Install tiktoken to enable OpenAI token counting") from exc
    raise

Prevention

Include tiktoken in environments that enable OpenAI compression/context features.
Exercise a token-count call in CI for every provider you configure, so missing optional deps fail in CI not production.
Remember the separate failure mode: once tiktoken exists, vocab download issues raise TiktokenLoadError, not this RuntimeError.

When it happens

Trigger: Calling any token-counting path that resolves an encoding for an OpenAI-family model (e.g. the OpenAI provider's count_tokens / compression sizing) when TIKTOKEN_AVAILABLE is False, i.e. tiktoken was never installed in the runtime environment.

Common situations: Running the proxy with the OpenAI provider enabled but tiktoken omitted from requirements; slim Docker images that strip optional extras; deploying on a host where a different virtualenv is active than the one where tiktoken was installed.

Related errors

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