mudler/LocalAI · error · FileNotFoundError

ONNX model not found: {onnx_path}

Error message

ONNX model not found: {onnx_path}

What it means

OnnxDirectEngine in the speaker-recognition backend requires an ONNX file to instantiate onnxruntime's InferenceSession. The path comes from the `model_path:` (or `onnx:`) option; relative names are resolved against the `_model_path` option (the gallery's models directory). If the resolved path does not exist on disk, __init__ raises FileNotFoundError before any session is created.

Source

Thrown at backend/python/speaker-recognition/engines.py:312

class OnnxDirectEngine:
    """Run a pre-exported ONNX speaker encoder (WeSpeaker / 3D-Speaker)."""

    name = "onnx-direct"

    def __init__(self, model_name: str, options: dict[str, str]):
        import onnxruntime as ort  # type: ignore

        # The gallery is expected to have dropped the ONNX file under
        # the models directory; accept either an absolute path or a
        # filename relative to _model_path.
        onnx_path = options.get("model_path") or options.get("onnx")
        if not onnx_path:
            raise ValueError("OnnxDirectEngine requires `model_path: <file.onnx>` in options")
        if not os.path.isabs(onnx_path):
            onnx_path = os.path.join(options.get("_model_path", ""), onnx_path)
        if not os.path.isfile(onnx_path):
            raise FileNotFoundError(f"ONNX model not found: {onnx_path}")

        providers = options.get("providers")
        if providers:
            provider_list = [p.strip() for p in providers.split(",") if p.strip()]
        else:
            provider_list = ["CPUExecutionProvider"]
        self._session = ort.InferenceSession(onnx_path, providers=provider_list)
        input_meta = self._session.get_inputs()[0]
        self._input_name = input_meta.name
        # Pre-exported speaker encoders come in two shapes:
        #   rank-2  [batch, samples]          — some 3D-Speaker exports feed raw waveform.
        #   rank-3  [batch, frames, n_mels]   — WeSpeaker and most Kaldi-lineage encoders
        #                                        expect pre-computed Kaldi FBank features.
        # We detect this at load time and branch in embed(), because feeding raw audio
        # into a rank-3 graph is exactly what triggered
        # "Invalid rank for input: feats Got: 2 Expected: 3".
        self._input_rank = len(input_meta.shape) if input_meta.shape is not None else 2
        self._expected_sr = int(options.get("sample_rate", "16000"))

View on GitHub (pinned to 44413a9d06)

Solutions

  1. Check that the file actually exists: ls the resolved path printed in the message (it is the joined _model_path + filename).
  2. If the file is elsewhere, set `model_path:` to the absolute path of the .onnx, or move/copy the file into the model's directory referenced by _model_path.
  3. Fix the gallery/model config so the ONNX artifact is downloaded into the models directory (verify the gallery URL and file name match).
  4. If the option key was misspelled, use `model_path: <file.onnx>` (or `onnx:`) in the model options.

Example fix

# before (model YAML)
options:
  model_path: speaker_encoder.onnx   # file not in models dir
# after — absolute path to the actual artifact
options:
  model_path: /models/speaker-recognition/speaker_encoder.onnx
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
import os

def validate_onnx_option(options: dict) -> str:
    p = options.get("model_path") or options.get("onnx")
    if not p:
        raise ValueError("missing model_path option")
    if not os.path.isabs(p):
        p = os.path.join(options.get("_model_path", ""), p)
    if not Path(p).is_file():
        raise FileNotFoundError(f"ONNX file missing: {p}")
    return p

Try / catch

try:
    engine = OnnxDirectEngine(model_name, options)
except FileNotFoundError as e:
    logger.error("model artifact missing: %s", e)
    raise ModelArtifactMissing(options.get("model_path")) from e

Prevention

When it happens

Trigger: Loading a speaker-recognition model whose YAML config has `model_path: speaker.onnx` but the gallery never downloaded the .onnx file into the model directory; passing a bare filename when `_model_path` is empty so the path resolves to `/speaker.onnx`; typo in the filename or the file was deleted/cleaned from the models dir.

Common situations: Gallery entry references an ONNX artifact that lives in a different repo subfolder (file lands under a subdirectory, not the dir given by _model_path); model installed via a partial download; option spelled differently (e.g. `onnx_path:` instead of `model_path:`) so an older absolute path option goes stale after the models dir moved.

Related errors

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/d88881f3304ed43d. Report an issue: GitHub.