{"record":{"id":"fd95222f28aceea4","repo":"headroomlabs-ai/headroom","slug":"tiktoken-encoding-encoding-name-r-load-timed-out","errorCode":null,"errorMessage":"tiktoken encoding {encoding_name!r} load timed out","messagePattern":"tiktoken encoding (.+?) load timed out","errorType":"exception","errorClass":"TiktokenLoadError","httpStatus":null,"severity":"error","filePath":"headroom/tokenizers/tiktoken_counter.py","lineNumber":143,"sourceCode":"        try:\n            box[\"enc\"] = tiktoken.get_encoding(encoding_name)\n        except BaseException as exc:  # noqa: BLE001 - re-raised in the calling thread\n            box[\"err\"] = exc\n\n    worker = threading.Thread(target=_load, name=f\"tiktoken-load-{encoding_name}\", daemon=True)\n    worker.start()\n    worker.join(_load_timeout_seconds())\n\n    if worker.is_alive():\n        _load_failed.add(encoding_name)\n        logger.warning(\n            \"tiktoken encoding %r did not load within %.1fs (likely a stalled vocab \"\n            \"download); falling back to token estimation. Pre-populate TIKTOKEN_CACHE_DIR \"\n            \"or tune HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS.\",\n            encoding_name,\n            _load_timeout_seconds(),\n        )\n        raise TiktokenLoadError(f\"tiktoken encoding {encoding_name!r} load timed out\")\n    if \"err\" in box:\n        raise box[\"err\"]\n    return box[\"enc\"]\n\n\ndef load_encoding(encoding_name: str) -> Any:\n    \"\"\"Public, bounded tiktoken-encoding loader.\n\n    Returns the tiktoken encoding, or raises :class:`TiktokenLoadError` if the\n    vocab can't be loaded within the timeout (see :func:`_get_encoding`, GH #956).\n    \"\"\"\n    return _get_encoding(encoding_name)\n\n\ndef get_encoding_for_model(model: str) -> str:\n    \"\"\"Get the tiktoken encoding name for a model.\n\n    Args:","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/tokenizers/tiktoken_counter.py#L125-L161","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pre-populate TIKTOKEN_CACHE_DIR during image build (run tiktoken.get_encoding once) so runtime loads are local.","Allow egress to openaipublic.blob.core.windows.net or route through a working proxy.","Increase the budget: HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS=60 for slow-but-working networks.","Catch TiktokenLoadError and fall back to the estimating counter for that request."],"exampleFix":"# before\nenc = load_encoding(\"o200k_base\")  # TiktokenLoadError after 10s stall\n\n# after\n# Dockerfile:\n#   ENV TIKTOKEN_CACHE_DIR=/opt/tiktoken\n#   RUN python -c \"import tiktoken; tiktoken.get_encoding('o200k_base')\"\nenc = load_encoding(\"o200k_base\")  # served from warm cache","handlingStrategy":"fallback","validationCode":"# pre-flight: warm the cache in the deploy pipeline\n# env: TIKTOKEN_CACHE_DIR=/opt/tiktoken\n# python -c \"import tiktoken; tiktoken.get_encoding('cl100k_base')\"","typeGuard":null,"tryCatchPattern":"from headroom.tokenizers.tiktoken_counter import TiktokenLoadError\ntry:\n    enc = load_encoding(encoding_name)\nexcept TiktokenLoadError as e:\n    logger.warning(\"tiktoken load failed (%s); estimating\", e)\n    enc = None  # count via EstimatingTokenCounter this request","preventionTips":["Pre-download vocabs at build time into TIKTOKEN_CACHE_DIR.","Tune HEADROOM_TIKTOKEN_LOAD_TIMEOUT_SECONDS for slow networks.","Ensure egress to openaipublic.blob.core.windows.net.","Treat a timeout as an environment defect to fix, not a per-request retry."],"tags":["tokenizer","tiktoken","timeout","network","caching","ci"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}