{"record":{"id":"b280f0ddbc5529c2","repo":"hacksider/Deep-Live-Cam","slug":"name-failed-to-initialize-gfpgan-onnx-session","errorCode":null,"errorMessage":"{NAME}: Failed to initialize GFPGAN ONNX session. Check logs.","messagePattern":"(.+?): Failed to initialize GFPGAN ONNX session\\. Check logs\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"modules/processors/frame/face_enhancer.py","lineNumber":114,"sourceCode":"                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\n    Returns:\n        (aligned_face, affine_matrix) or (None, None) on failure.\n    \"\"\"\n    # Scale the 512-base template to the desired output size\n    scale = output_size / 512.0","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/hacksider/Deep-Live-Cam/blob/987f6b392b1740623b3fa8a5cb46fdd0b7e185b9/modules/processors/frame/face_enhancer.py#L96-L132","documentation":"RuntimeError raised at the end of get_face_enhancer (modules/processors/frame/face_enhancer.py) when FACE_ENHANCER is still None after the locked initialization block. It is a belt-and-braces guard: normally the failure paths raise earlier (FileNotFoundError for a missing file, RuntimeError for a load failure that also resets the global to None). Reaching this line means initialization finished without raising yet produced no session — e.g. create_onnx_session returned None instead of raising, or the global was concurrently cleared.","triggerScenarios":"create_onnx_session returns None instead of raising on a degenerate input; a previous failed load set FACE_ENHANCER = None and a subsequent call takes a code path that skips assignment; any logic change where the lock block exits without either raising or assigning a session.","commonSituations":"Rarely seen in practice — it is a defensive assertion after the lock. Most users who see 'Check logs' style errors here actually hit the except-branch error [3] on the previous attempt; the message advises inspecting the earlier printed diagnostics.","solutions":["Reproduce and check the console output above this error — an earlier 'Error loading GFPGAN ONNX model: ...' line from the except branch names the root cause; fix that.","Verify create_onnx_session cannot return None for your onnxruntime version; upgrade or patch it to raise instead.","Confirm the model file exists and loads (fixes for errors [2] and [3] also resolve most paths into this guard)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    session = get_face_enhancer()\nexcept RuntimeError as e:\n    if \"Check logs\" in str(e):\n        # a defensive guard fired; inspect earlier diagnostics for the real cause\n        log.error('Enhancer init produced no session; earlier load errors above are authoritative')\n    raise","preventionTips":["Capture stdout/print diagnostics into a logger so 'Check logs' has logs to check.","Ensure create_onnx_session raises rather than returning None on failure.","Treat this error as a symptom: resolve the underlying load failure (errors 2/3) first."],"tags":["python","onnxruntime","defensive-check","singleton","face-enhancement"],"backgroundTag":null,"analyzedSha":"987f6b392b1740623b3fa8a5cb46fdd0b7e185b9","analyzedAt":"2026-08-14T19:48:25.860Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}