{"record":{"id":"cc6b9d396391cbfe","repo":"hacksider/Deep-Live-Cam","slug":"name-failed-to-load-gfpgan-onnx-model-e","errorCode":null,"errorMessage":"{NAME}: Failed to load GFPGAN ONNX model: {e}","messagePattern":"(.+?): Failed to load GFPGAN ONNX model: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"modules/processors/frame/face_enhancer.py","lineNumber":109,"sourceCode":"                output_info = FACE_ENHANCER.get_outputs()[0]\n                active_providers = FACE_ENHANCER.get_providers()\n                print(\n                    f\"{NAME}: GFPGAN ONNX model loaded successfully.\"\n                )\n                print(\n                    f\"{NAME}: Input: {input_info.name}, \"\n                    f\"shape: {input_info.shape}, type: {input_info.type}\"\n                )\n                print(\n                    f\"{NAME}: Output: {output_info.name}, \"\n                    f\"shape: {output_info.shape}, type: {output_info.type}\"\n                )\n                print(f\"{NAME}: Active providers: {active_providers}\")\n\n            except Exception as e:\n                print(f\"{NAME}: Error loading GFPGAN ONNX model: {e}\")\n                FACE_ENHANCER = None\n                raise RuntimeError(\n                    f\"{NAME}: Failed to load GFPGAN ONNX model: {e}\"\n                )\n\n    if FACE_ENHANCER is None:\n        raise RuntimeError(\n            f\"{NAME}: Failed to initialize GFPGAN ONNX session. Check logs.\"\n        )\n\n    return FACE_ENHANCER\n\n\ndef _align_face(\n    frame: Frame, landmarks_5: np.ndarray, output_size: int\n) -> tuple:\n    \"\"\"\n    Align and crop a face from the frame using 5-point landmarks and the\n    standard FFHQ template.\n","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/hacksider/Deep-Live-Cam/blob/987f6b392b1740623b3fa8a5cb46fdd0b7e185b9/modules/processors/frame/face_enhancer.py#L91-L127","documentation":"RuntimeError raised in get_face_enhancer (modules/processors/frame/face_enhancer.py) when create_onnx_session throws while loading gfpgan-1024.onnx. The original exception is printed and re-wrapped with its message, and the cached FACE_ENHANCER global is reset to None so the next call retries from scratch. The root cause is whatever the embedded {e} says — typically a corrupt/incompatible model file, a missing execution provider, or an onnxruntime version mismatch.","triggerScenarios":"gfpgan-1024.onnx is truncated or corrupt (failed download) so onnxruntime fails to parse it; onnxruntime version too old/new for the model's opset; a configured execution provider (e.g. CUDAExecutionProvider) is unavailable in the installed onnxruntime build; incompatible CPU instruction set on old hardware.","commonSituations":"Partial model download (file exists with wrong size/checksum); installing onnxruntime instead of onnxruntime-gpu and then requiring CUDA providers; mismatch between the ONNX opset used to export GFPGAN and the runtime version; system lacking AVX; model artifact from a different conversion pipeline than the code expects.","solutions":["Read the wrapped message: the trailing {e} names the real cause (e.g. invalid protobuf, provider not found, ORT format unsupported) — fix that first.","If the file may be corrupt, delete gfpgan-1024.onnx and re-download it; verify its size/checksum against the project's documented value.","Ensure the onnxruntime package matches the providers configured in modules.globals (onnxruntime-gpu for CUDAExecutionProvider) and is a version compatible with the model's opset.","If a specific provider fails, fall back to CPUExecutionProvider in the provider configuration to confirm the model itself loads."],"exampleFix":"# before\n# provider config includes CUDAExecutionProvider with CPU-only onnxruntime\n\n# after\n# pip install onnxruntime-gpu  # or restrict providers to what the build supports:\nproviders = ['CUDAExecutionProvider', 'CPUExecutionProvider'] if is_gpu_available() else ['CPUExecutionProvider']","handlingStrategy":"try-catch","validationCode":"import onnxruntime as ort\n# sanity-check the file parses and providers exist before the app needs it\nsess_check = ort.InferenceSession(model_path, providers=['CPUExecutionProvider'])\nassert sess_check.get_inputs(), 'model has no inputs'","typeGuard":null,"tryCatchPattern":"try:\n    session = get_face_enhancer()\nexcept RuntimeError as e:\n    # the trailing {e} carries the root cause; surface it, do not retry blindly\n    log.error('GFPGAN load failed: %s', e)\n    raise","preventionTips":["Verify model file checksum/size right after download to catch truncation.","Match onnxruntime package (gpu vs cpu) to the configured execution providers.","Smoke-test model loading in a startup check so failures surface at boot, not mid-request."],"tags":["python","onnxruntime","model-loading","execution-providers","exception-wrapping"],"backgroundTag":null,"analyzedSha":"987f6b392b1740623b3fa8a5cb46fdd0b7e185b9","analyzedAt":"2026-08-14T19:48:25.860Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}