{"record":{"id":"42781a8cf9319ed9","repo":"mudler/LocalAI","slug":"unknown-engine-name-r","errorCode":null,"errorMessage":"unknown engine: {name!r}","messagePattern":"unknown engine: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/insightface/engines.py","lineNumber":573,"sourceCode":"    if model_dir:\n        candidates.append(os.path.join(model_dir, os.path.basename(path)))\n        candidates.append(os.path.join(model_dir, stripped))\n    script_dir = os.path.dirname(os.path.abspath(__file__))\n    candidates.append(os.path.join(script_dir, stripped))\n    for c in candidates:\n        if os.path.isfile(c):\n            return c\n    return path\n\n\ndef build_engine(name: str) -> FaceEngine:\n    \"\"\"Factory for the engine selected by LoadModel options.\"\"\"\n    key = name.strip().lower()\n    if key in (\"\", \"insightface\"):\n        return InsightFaceEngine()\n    if key in (\"onnx_direct\", \"onnx-direct\", \"opencv\"):\n        return OnnxDirectEngine()\n    raise ValueError(f\"unknown engine: {name!r}\")\n","sourceCodeStart":555,"sourceCodeEnd":574,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/insightface/engines.py#L555-L574","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use one of the accepted values: 'insightface' (or empty/omitted) for the default, 'onnx_direct'/'onnx-direct'/'opencv' for the direct ONCV/ONNX path","Check the echoed name in the error message for typos or hidden whitespace/unicode"],"exampleFix":"# before\noptions:\n  engine: arcface\n\n# after\noptions:\n  engine: onnx_direct","handlingStrategy":"validation","validationCode":"VALID_ENGINES = {\"\", \"insightface\", \"onnx_direct\", \"onnx-direct\", \"opencv\"}\n\ndef normalize_engine(name: str) -> str:\n    key = name.strip().lower()\n    if key not in VALID_ENGINES:\n        raise ValueError(f\"unknown engine {name!r}; valid: insightface, onnx_direct, opencv\")\n    return key","typeGuard":"def is_known_engine(name: str) -> bool:\n    return isinstance(name, str) and name.strip().lower() in {\"\", \"insightface\", \"onnx_direct\", \"onnx-direct\", \"opencv\"}","tryCatchPattern":"try:\n    engine = build_engine(name)\nexcept ValueError:\n    # fall back to the default engine only if the user did not explicitly choose one\n    engine = build_engine(\"insightface\") if name == \"\" else re_raise()","preventionTips":["Expose engine choice in config as an enum/limited dropdown, never free text","Fail fast at config parse time with the list of valid values"],"tags":["python","insightface","configuration","validation"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}