headroomlabs-ai/headroom · error · TiktokenLoadError

tiktoken encoding {encoding_name!r} load timed out

Error message

tiktoken encoding {encoding_name!r} load timed out

What it means

TiktokenLoadError raised when loading a tiktoken encoding exceeds HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS (default 10s): tiktoken's vocab fetch has no built-in network timeout, so headroom runs it on a daemon thread and joins with a timeout. On timeout the encoding is added to _load_failed (causing later fail-fast errors) and a warning suggests pre-populating TIKTOKEN_CACHE_DIR or tuning the env var.

Source

Thrown at headroom/tokenizers/tiktoken_counter.py:143

        try:
            box["enc"] = tiktoken.get_encoding(encoding_name)
        except BaseException as exc:  # noqa: BLE001 - re-raised in the calling thread
            box["err"] = exc

    worker = threading.Thread(target=_load, name=f"tiktoken-load-{encoding_name}", daemon=True)
    worker.start()
    worker.join(_load_timeout_seconds())

    if worker.is_alive():
        _load_failed.add(encoding_name)
        logger.warning(
            "tiktoken encoding %r did not load within %.1fs (likely a stalled vocab "
            "download); falling back to token estimation. Pre-populate TIKTOKEN_CACHE_DIR "
            "or tune HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS.",
            encoding_name,
            _load_timeout_seconds(),
        )
        raise TiktokenLoadError(f"tiktoken encoding {encoding_name!r} load timed out")
    if "err" in box:
        raise box["err"]
    return box["enc"]


def load_encoding(encoding_name: str) -> Any:
    """Public, bounded tiktoken-encoding loader.

    Returns the tiktoken encoding, or raises :class:`TiktokenLoadError` if the
    vocab can't be loaded within the timeout (see :func:`_get_encoding`, GH #956).
    """
    return _get_encoding(encoding_name)


def get_encoding_for_model(model: str) -> str:
    """Get the tiktoken encoding name for a model.

    Args:

View on GitHub (pinned to 322425c43b)

Solutions

1. Pre-populate TIKTOKEN_CACHE_DIR during image build (run tiktoken.get_encoding once) so runtime loads are local.
2. Allow egress to openaipublic.blob.core.windows.net or route through a working proxy.
3. Increase the budget: HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS=60 for slow-but-working networks.
4. Catch TiktokenLoadError and fall back to the estimating counter for that request.

Example fix

# before
enc = load_encoding("o200k_base")  # TiktokenLoadError after 10s stall

# after
# Dockerfile:
#   ENV TIKTOKEN_CACHE_DIR=/opt/tiktoken
#   RUN python -c "import tiktoken; tiktoken.get_encoding('o200k_base')"
enc = load_encoding("o200k_base")  # served from warm cache

# pre-flight: warm the cache in the deploy pipeline
# env: TIKTOKEN_CACHE_DIR=/opt/tiktoken
# python -c "import tiktoken; tiktoken.get_encoding('cl100k_base')"

from headroom.tokenizers.tiktoken_counter import TiktokenLoadError
try:
    enc = load_encoding(encoding_name)
except TiktokenLoadError as e:
    logger.warning("tiktoken load failed (%s); estimating", e)
    enc = None  # count via EstimatingTokenCounter this request

When it happens

Trigger: First use of an encoding whose .tiktoken vocab file must be fetched from openaipublic blob storage through a slow/blocked network; cold containers with empty caches; restrictive egress rules in k8s/CI that stall the download.

Common situations: Air-gapped or egress-filtered deployments; corporate proxies that black-hole unknown hosts; CI images without a baked-in tiktoken cache; large vocabs on high-latency links.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• tiktoken encoding {encoding_name!r} previously failed to loa
• headroom proxy was not ready at {url}: {last_error}
• upstream request failed: {0}
• `{' '.join(cmd)}` produced no output for {idle_cap}s. Check
• Encoding not available for {self.model} - tokenizer {self.to

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