hacksider/Deep-Live-Cam · critical · RuntimeError

{NAME}: Failed to load GFPGAN ONNX model: {e}

Error message

{NAME}: Failed to load GFPGAN ONNX model: {e}

What it means

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.

Source

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

                output_info = FACE_ENHANCER.get_outputs()[0]
                active_providers = FACE_ENHANCER.get_providers()
                print(
                    f"{NAME}: GFPGAN ONNX model loaded successfully."
                )
                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.

View on GitHub (pinned to 987f6b392b)

Solutions

1. Read the wrapped message: the trailing {e} names the real cause (e.g. invalid protobuf, provider not found, ORT format unsupported) — fix that first.
2. If the file may be corrupt, delete gfpgan-1024.onnx and re-download it; verify its size/checksum against the project's documented value.
3. 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.
4. If a specific provider fails, fall back to CPUExecutionProvider in the provider configuration to confirm the model itself loads.

Example fix

# before
# provider config includes CUDAExecutionProvider with CPU-only onnxruntime

# after
# pip install onnxruntime-gpu  # or restrict providers to what the build supports:
providers = ['CUDAExecutionProvider', 'CPUExecutionProvider'] if is_gpu_available() else ['CPUExecutionProvider']

import onnxruntime as ort
# sanity-check the file parses and providers exist before the app needs it
sess_check = ort.InferenceSession(model_path, providers=['CPUExecutionProvider'])
assert sess_check.get_inputs(), 'model has no inputs'

try:
    session = get_face_enhancer()
except RuntimeError as e:
    # the trailing {e} carries the root cause; surface it, do not retry blindly
    log.error('GFPGAN load failed: %s', e)
    raise

When it happens

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

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

Related errors

• {NAME}: Model not found at {model_path}
• {NAME}: Failed to initialize GFPGAN ONNX session. Check logs
• embeddings must not be empty
• max_k must be at least 1
• Model file not found: {model_path}

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