headroomlabs-ai/headroom · error · FileNotFoundError

No loadable ONNX artifact in {model_id}; tried {_onnx_filena

Error message

No loadable ONNX artifact in {model_id}; tried {_onnx_filename_candidates()}

What it means

Terminal FileNotFoundError from the ONNX candidate loop in _load_kompress_pytorch's sibling loader: every candidate filename from _onnx_filename_candidates() was tried and each either failed to download, failed InferenceSession load, or failed the _smoke_run — and since downloading was allowed (or the failure was not a pure cache miss), the loop exits with this aggregated error chaining the last underlying exception. Notably, some onnxruntime builds accept an int8 MatMulNBits model at load but reject it at execution; the smoke run catches that and falls through, so a restrictive ORT build can exhaust all candidates.

Source

Thrown at headroom/transforms/kompress_compressor.py:686

        try:
            session = ort.InferenceSession(
                onnx_path,
                _onnx_session_options(ort),
                providers=providers,
            )
            _smoke_run(session)
            return session
        except Exception as exc:
            last_err = exc
            logger.warning(
                "ONNX artifact %r from %s is unusable (%s); trying next candidate",
                filename,
                model_id,
                exc,
            )
    if not allow_download and cache_miss:
        raise KompressModelNotCached(model_id) from last_err
    raise FileNotFoundError(
        f"No loadable ONNX artifact in {model_id}; tried {_onnx_filename_candidates()}"
    ) from last_err


def _load_kompress_onnx(
    model_id: str,
    *,
    use_coreml: bool = False,
    allow_download: bool = True,
) -> tuple[Any, Any, str]:
    """Download ONNX INT8 model from HuggingFace and load with onnxruntime.

    When ``allow_download`` is ``False`` the model and tokenizer are loaded from
    the local cache only; a cache miss raises :class:`KompressModelNotCached`
    instead of hitting the network.
    """
    with _kompress_lock:
        if model_id in _kompress_cache:

View on GitHub (pinned to 322425c43b)

Solutions

Check the chained cause (raise.from last_err) — it tells you whether it was network, missing file, or ORT execution failure.
Upgrade onnxruntime to a build supporting MatMulNBits contrib ops, then retry.
Verify network/egress to huggingface.co and that the model repo still ships the ONNX filenames listed in the error.
Fall back to the PyTorch loader (ensure torch is installed) — the top-level loader already tries this, so a torch install fixes the end-to-end path.

Example fix

# before
session = _load_kompress_pytorch_session(model_id)  # FileNotFoundError

# after
try:
    session = load_kompress_model(model_id, prefer_backend="onnx")
except FileNotFoundError:
    session = load_kompress_model(model_id, prefer_backend="torch")  # needs torch installed

Defensive patterns

Strategy: fallback

Try / catch

try:
    session = load_kompress_model(model_id, backend="onnx")
except FileNotFoundError as e:
    logger.warning("ONNX unusable (%s); trying PyTorch", e)
    session = load_kompress_model(model_id, backend="torch")

Prevention

Install onnxruntime builds that support MatMulNBits contrib ops (or keep torch as fallback).
Verify HF egress and repo contents (ONNX filenames) before deploying offline.
Inspect the chained exception — it distinguishes network vs load vs smoke-run failure.

When it happens

Trigger: Loading Kompress ONNX when: the HuggingFace repo lacks/removed the ONNX artifacts, network access fails for every candidate, or the installed onnxruntime cannot execute any offered artifact (int8 contrib op unsupported and fp32 candidate also unavailable).

Common situations: Old/limited onnxruntime builds (no contrib ops), corporate proxies blocking HF downloads, a model repo revision that dropped ONNX files, corrupted partial downloads.

Related errors

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