{"record":{"id":"e190848f9f021475","repo":"headroomlabs-ai/headroom","slug":"model-id","errorCode":null,"errorMessage":"{model_id}","messagePattern":"\\{model_id\\}","errorType":"exception","errorClass":"KompressModelNotCached","httpStatus":null,"severity":"error","filePath":"headroom/transforms/kompress_compressor.py","lineNumber":685,"sourceCode":"            ort = onnxruntime\n        try:\n            session = ort.InferenceSession(\n                onnx_path,\n                _onnx_session_options(ort),\n                providers=providers,\n            )\n            _smoke_run(session)\n            return session\n        except Exception as exc:\n            last_err = exc\n            logger.warning(\n                \"ONNX artifact %r from %s is unusable (%s); trying next candidate\",\n                filename,\n                model_id,\n                exc,\n            )\n    if not allow_download and cache_miss:\n        raise KompressModelNotCached(model_id) from last_err\n    raise FileNotFoundError(\n        f\"No loadable ONNX artifact in {model_id}; tried {_onnx_filename_candidates()}\"\n    ) from last_err\n\n\ndef _load_kompress_onnx(\n    model_id: str,\n    *,\n    use_coreml: bool = False,\n    allow_download: bool = True,\n) -> tuple[Any, Any, str]:\n    \"\"\"Download ONNX INT8 model from HuggingFace and load with onnxruntime.\n\n    When ``allow_download`` is ``False`` the model and tokenizer are loaded from\n    the local cache only; a cache miss raises :class:`KompressModelNotCached`\n    instead of hitting the network.\n    \"\"\"\n    with _kompress_lock:","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/kompress_compressor.py#L667-L703","documentation":"This is KompressModelNotCached(model_id) (a RuntimeError subclass defined at kompress_compressor.py:138), raised when allow_download=False and every ONNX filename candidate was a cache miss (_NOT_CACHED_ERRORS = (OSError,)). It exists so cache-only callers (e.g. deferred model warm-up) can distinguish 'not downloaded yet' from a real load failure and avoid triggering network downloads.","triggerScenarios":"Loading the Kompress model with allow_download=False (cache-only mode) before the model artifacts were ever downloaded from HuggingFace in that environment.","commonSituations":"Offline or egress-restricted deployments; a fresh container/CI runner with a cold HF cache; calling a warm-up API that deliberately forbids network and expects to defer.","solutions":["Pre-warm the cache once with downloads allowed (run a load with allow_download=True, or run huggingface-cli download <model_id> in an image-build step).","Catch KompressModelNotCached at the caller and defer/skip Kompress compression for this request instead of failing it.","Bake the HF model cache into the Docker image and point HF_HOME at it."],"exampleFix":"# before\nload_kompress_model(model_id, allow_download=False)  # raises KompressModelNotCached\n\n# after\ntry:\n    load_kompress_model(model_id, allow_download=False)\nexcept KompressModelNotCached:\n    use_fallback_compressor()  # defer; or warm cache at deploy time","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    model = load_kompress_model(model_id, allow_download=False)\nexcept KompressModelNotCached:\n    logger.info(\"Kompress model %s not cached; deferring\", model_id)\n    model = None  # defer warm-up; use fallback compressors","preventionTips":["Warm the HF cache at deploy/image-build time with downloads enabled.","Treat KompressModelNotCached as a control-flow signal, not a failure — never retry in a loop.","Set HF_HOME to a persistent, pre-populated cache location."],"tags":["model-loading","cache","offline","huggingface"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}