hacksider/Deep-Live-Cam · error · RuntimeError

{NAME}: Failed to initialize GFPGAN ONNX session. Check logs

Error message

{NAME}: Failed to initialize GFPGAN ONNX session. Check logs.

What it means

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.

Source

Thrown at modules/processors/frame/face_enhancer.py:114

                print(
                    f"{NAME}: Input: {input_info.name}, "
                    f"shape: {input_info.shape}, type: {input_info.type}"
                )
                print(
                    f"{NAME}: Output: {output_info.name}, "
                    f"shape: {output_info.shape}, type: {output_info.type}"
                )
                print(f"{NAME}: Active providers: {active_providers}")

            except Exception as e:
                print(f"{NAME}: Error loading GFPGAN ONNX model: {e}")
                FACE_ENHANCER = None
                raise RuntimeError(
                    f"{NAME}: Failed to load GFPGAN ONNX model: {e}"
                )

    if FACE_ENHANCER is None:
        raise RuntimeError(
            f"{NAME}: Failed to initialize GFPGAN ONNX session. Check logs."
        )

    return FACE_ENHANCER


def _align_face(
    frame: Frame, landmarks_5: np.ndarray, output_size: int
) -> tuple:
    """
    Align and crop a face from the frame using 5-point landmarks and the
    standard FFHQ template.

    Returns:
        (aligned_face, affine_matrix) or (None, None) on failure.
    """
    # Scale the 512-base template to the desired output size
    scale = output_size / 512.0

View on GitHub (pinned to 987f6b392b)

Solutions

1. 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.
2. Verify create_onnx_session cannot return None for your onnxruntime version; upgrade or patch it to raise instead.
3. Confirm the model file exists and loads (fixes for errors [2] and [3] also resolve most paths into this guard).

try:
    session = get_face_enhancer()
except RuntimeError as e:
    if "Check logs" in str(e):
        # a defensive guard fired; inspect earlier diagnostics for the real cause
        log.error('Enhancer init produced no session; earlier load errors above are authoritative')
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• {NAME}: Model not found at {model_path}
• {NAME}: Failed to load GFPGAN ONNX model: {e}
• Model file not found: {model_path}
• Model file not found: {model_path}
• embeddings must not be empty

AI-assisted analysis of hacksider/Deep-Live-Cam@987f6b392b (2026-08-14). Data as JSON: /api/errors/b280f0ddbc5529c2. Report an issue: GitHub.