{"record":{"id":"f46cafbf87d8be68","repo":"deepinsight/insightface","slug":"operation-name-str-e","errorCode":null,"errorMessage":"{operation_name}: {str(e)}","messagePattern":"\\{operation_name\\}: \\{str\\(e\\)\\}","errorType":"exception","errorClass":"ProcessingError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/exception.py","lineNumber":236,"sourceCode":"    if session is None or session._sess is None:\n        raise ResourceError(\n            f\"{operation}: Session not initialized\",\n            errcode.HERR_INVALID_CONTEXT_HANDLE\n        )\n\n\n# === Exception handling decorators for special scenarios ===\n\ndef handle_c_api_errors(operation_name: str):\n    \"\"\"Decorator for wrapping C API calls\"\"\"\n    def decorator(func):\n        def wrapper(*args, **kwargs):\n            try:\n                return func(*args, **kwargs)\n            except Exception as e:\n                if not isinstance(e, InspireFaceError):\n                    # Wrap non-InspireFace exceptions as ProcessingError\n                    raise ProcessingError(\n                        f\"{operation_name}: {str(e)}\",\n                        context={'original_exception': type(e).__name__}\n                    ) from e\n                raise\n        return wrapper\n    return decorator\n","sourceCodeStart":218,"sourceCodeEnd":243,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/exception.py#L218-L243","documentation":"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.","triggerScenarios":"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.","commonSituations":"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: ...'.","solutions":["Read the text after the colon and the chained 'The above exception was the direct cause' traceback — fix that root cause","Reproduce by calling the underlying step directly (e.g. ImageStream.load_from_cv_image) to strip the wrapper","If it's an ArgumentError, correct argument types/order for the wrapped API"],"exampleFix":"# before\ntry:\n    session.face_detection(img)\nexcept ProcessingError as e:\n    print(e)  # 'Face detection: ctypes.ArgumentError: ...'\n# after — inspect the chained cause for the real error\nexcept ProcessingError as e:\n    log.error('root cause: %r', e.__cause__)\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from inspireface.modules.exception import ProcessingError\ntry:\n    result = session.face_detection(img)\nexcept ProcessingError as e:\n    log.exception('root cause: %r', e.__cause__)\n    raise","preventionTips":["Always inspect __cause__ of ProcessingError — the wrapper hides the root exception type","Reproduce failures with lower-level calls (ImageStream.load_from_cv_image) to bypass the wrapper"],"tags":["error-wrapping","decorator","debugging","inspireface"],"backgroundTag":"wrapped-exception-context","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}