deepinsight/insightface · error · ProcessingError

{operation_name}: {str(e)}

Error message

{operation_name}: {str(e)}

What it means

This is the @handle_c_api_errors-style decorator's wrapper: any non-InspireFaceError exception escaping the decorated function is re-raised as ProcessingError with the operation name prepended and the original exception chained via 'from e'. It is a normalization layer, so the message's suffix is the real underlying error text.

Solutions

1. Read the text after the colon and the chained 'The above exception was the direct cause' traceback — fix that root cause
2. Reproduce by calling the underlying step directly (e.g. ImageStream.load_from_cv_image) to strip the wrapper
3. If it's an ArgumentError, correct argument types/order for the wrapped API

Example fix

# before
try:
    session.face_detection(img)
except ProcessingError as e:
    print(e)  # 'Face detection: ctypes.ArgumentError: ...'
# after — inspect the chained cause for the real error
except ProcessingError as e:
    log.error('root cause: %r', e.__cause__)
    raise

from inspireface.modules.exception import ProcessingError
try:
    result = session.face_detection(img)
except ProcessingError as e:
    log.exception('root cause: %r', e.__cause__)
    raise

When it happens

Trigger: Any unexpected exception inside a wrapped operation — e.g. a ctypes ArgumentError from wrong argument marshalling, a numpy error while preprocessing, or the native call raising something not already mapped to InspireFaceError.

Common situations: Passing subtly wrong types that survive early validation but break ctypes; OpenCV/numpy runtime errors inside the pipeline; bugs that used to surface as raw tracebacks now appearing as 'Face detection: ...'.

Related errors

• exec_param must be SessionCustomParameter or int
• Failed to download model
• Failed to launch InspireFace automatically
• HERR_INVALID_CONTEXT_HANDLE
• HERR_INVALID_FACE_FEATURE

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/f46cafbf87d8be68. Report an issue: GitHub.

Appendix: source

Thrown at cpp-package/inspireface/python/inspireface/modules/exception.py:236

    if session is None or session._sess is None:
        raise ResourceError(
            f"{operation}: Session not initialized",
            errcode.HERR_INVALID_CONTEXT_HANDLE
        )


# === Exception handling decorators for special scenarios ===

def handle_c_api_errors(operation_name: str):
    """Decorator for wrapping C API calls"""
    def decorator(func):
        def wrapper(*args, **kwargs):
            try:
                return func(*args, **kwargs)
            except Exception as e:
                if not isinstance(e, InspireFaceError):
                    # Wrap non-InspireFace exceptions as ProcessingError
                    raise ProcessingError(
                        f"{operation_name}: {str(e)}",
                        context={'original_exception': type(e).__name__}
                    ) from e
                raise
        return wrapper
    return decorator

View on GitHub (pinned to 7fadd420c2)