mudler/LocalAI · error · ValueError

unknown engine: {name!r}

Error message

unknown engine: {name!r}

What it means

Raised by build_engine(), the factory that maps the LoadModel 'engine' option to a FaceEngine implementation. It normalizes the name (strip + lowercase) and only accepts '', 'insightface', 'onnx_direct', 'onnx-direct', and 'opencv'. Any other string raises ValueError with the offending name echoed.

Source

Thrown at backend/python/insightface/engines.py:573

    if model_dir:
        candidates.append(os.path.join(model_dir, os.path.basename(path)))
        candidates.append(os.path.join(model_dir, stripped))
    script_dir = os.path.dirname(os.path.abspath(__file__))
    candidates.append(os.path.join(script_dir, stripped))
    for c in candidates:
        if os.path.isfile(c):
            return c
    return path


def build_engine(name: str) -> FaceEngine:
    """Factory for the engine selected by LoadModel options."""
    key = name.strip().lower()
    if key in ("", "insightface"):
        return InsightFaceEngine()
    if key in ("onnx_direct", "onnx-direct", "opencv"):
        return OnnxDirectEngine()
    raise ValueError(f"unknown engine: {name!r}")

View on GitHub (pinned to 44413a9d06)

Solutions

1. Use one of the accepted values: 'insightface' (or empty/omitted) for the default, 'onnx_direct'/'onnx-direct'/'opencv' for the direct ONCV/ONNX path
2. Check the echoed name in the error message for typos or hidden whitespace/unicode

Example fix

# before
options:
  engine: arcface

# after
options:
  engine: onnx_direct

VALID_ENGINES = {"", "insightface", "onnx_direct", "onnx-direct", "opencv"}

def normalize_engine(name: str) -> str:
    key = name.strip().lower()
    if key not in VALID_ENGINES:
        raise ValueError(f"unknown engine {name!r}; valid: insightface, onnx_direct, opencv")
    return key

def is_known_engine(name: str) -> bool:
    return isinstance(name, str) and name.strip().lower() in {"", "insightface", "onnx_direct", "onnx-direct", "opencv"}

try:
    engine = build_engine(name)
except ValueError:
    # fall back to the default engine only if the user did not explicitly choose one
    engine = build_engine("insightface") if name == "" else re_raise()

When it happens

Trigger: Calling build_engine('onnx') (missing _direct), 'yunet', 'arcface', or any typo like 'insight-face'; passing an engine name with leading/trailing whitespace is fine (it is stripped) but wrong casing alone is also fine (lowercased), so the error only fires on genuinely unknown names.

Common situations: User invents an engine name from the underlying model file (e.g. 'buffalo_l'); docs or examples drift from the accepted list; the engine option is set to a backend name instead of a face-engine name.

Related errors

• onnx_direct engine requires both detector_onnx and recognize
• resolution must be 480p or 720p
• base_model must point to a LongCat-Video checkpoint
• request needs {segments} avatar segments, but max_segments i
• {name} must be true or false

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