{"record":{"id":"bedeac59d7c44bcb","repo":"deepinsight/insightface","slug":"herr-invalid-param","errorCode":"HERR_INVALID_PARAM","errorMessage":"{operation}: Input must be a numpy array","messagePattern":"(.+?): Input must be a numpy array","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/exception.py","lineNumber":175,"sourceCode":"                exception_class = ResourceError\n            elif category == 'hardware':\n                exception_class = HardwareError\n            elif category == 'feature_hub':\n                exception_class = FeatureHubError\n            break\n    \n    # Raise corresponding exception\n    raise exception_class(message, error_code, **context)\n\n\n# === Convenient validation functions ===\n\ndef validate_image_format(image, operation: str = \"Image validation\"):\n    \"\"\"Validate image format\"\"\"\n    import numpy as np\n    \n    if not isinstance(image, np.ndarray):\n        raise InvalidInputError(\n            f\"{operation}: Input must be a numpy array\",\n            errcode.HERR_INVALID_PARAM,\n            input_type=type(image).__name__\n        )\n    \n    if len(image.shape) != 3:\n        raise InvalidInputError(\n            f\"{operation}: Image must be 3-dimensional (H, W, C)\",\n            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,\n            actual_shape=image.shape\n        )\n    \n    h, w, c = image.shape\n    if c not in [3, 4]:\n        raise InvalidInputError(\n            f\"{operation}: Image must have 3 or 4 channels\",\n            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,\n            actual_channels=c","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/exception.py#L157-L193","documentation":"validate_image_format() requires the image argument to be a numpy.ndarray before it can inspect shape/channels; anything else raises InvalidInputError with HERR_INVALID_PARAM. It is the first gate in image validation used by load_from_cv_image and the session pipeline.","triggerScenarios":"Passing a PIL.Image, file path string, bytes, a mishandled cv2 VideoCapture result, or None to InspireFaceSession.face_detection / face_pipeline / face_feature_extract or ImageStream.load_from_cv_image.","commonSituations":"Switching from a PIL-based pipeline or copying sample code that loads with PIL; forgetting cv2.imread returns None when a file doesn't exist and passing that None onward; feeding a torch tensor or URL string directly.","solutions":["Convert first: np_img = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR) or load with cv2.imread(path)","If cv2.imread was used, check it didn't return None (bad path) before passing it on","For tensors: tensor.numpy().transpose(1, 2, 0)"],"exampleFix":"# before\nimg = Image.open('a.jpg')\nsession.face_detection(img)\n# after\nimport cv2, numpy as np\nimg = cv2.cvtColor(np.array(Image.open('a.jpg')), cv2.COLOR_RGB2BGR)\nsession.face_detection(img)","handlingStrategy":"type-guard","validationCode":"import numpy as np\ndef as_bgr_ndarray(img):\n    if not isinstance(img, np.ndarray):\n        import cv2\n        img = cv2.cvtColor(np.asarray(img), cv2.COLOR_RGB2BGR)\n    return img","typeGuard":"def is_valid_image(img) -> bool:\n    import numpy as np\n    return isinstance(img, np.ndarray)","tryCatchPattern":"from inspireface.modules.exception import InvalidInputError\ntry:\n    session.face_detection(img)\nexcept InvalidInputError as e:\n    raise TypeError('convert image to BGR ndarray first') from e","preventionTips":["Standardize on cv2.imread at your pipeline entry","Check cv2.imread result for None before passing downstream"],"tags":["validation","numpy","image","inspireface"],"backgroundTag":"input-type-validation-failed","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}