{"record":{"id":"ffda316671351c94","repo":"deepinsight/insightface","slug":"herr-invalid-image-stream-param","errorCode":"HERR_INVALID_IMAGE_STREAM_PARAM","errorMessage":"{operation}: Image must be 3-dimensional (H, W, C)","messagePattern":"(.+?): Image must be 3-dimensional \\(H, W, C\\)","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/exception.py","lineNumber":182,"sourceCode":"    # 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\n        )\n\n\ndef validate_feature_data(data, operation: str = \"Feature validation\"):\n    \"\"\"Validate feature data format\"\"\"\n    import numpy as np\n    ","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/exception.py#L164-L200","documentation":"After confirming the input is an ndarray, validate_image_format() checks len(image.shape) == 3 (H, W, C); a 2-D grayscale or 4-D batched array raises InvalidInputError with HERR_INVALID_IMAGE_STREAM_PARAM. The native stream API only accepts interleaved 3-D frames.","triggerScenarios":"Passing a grayscale image loaded with cv2.imread(path, cv2.IMREAD_GRAYSCALE), a batched NCHW/NHWC tensor, or a masked/extra-dim array to face_detection / load_from_cv_image.","commonSituations":"Preprocessing pipelines that squeeze/expand dims, model-centric code assuming channel-first tensors, grayscale camera feeds converted without color conversion.","solutions":["Grayscale: img = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)","Tensor input: arr = tensor.squeeze(0).permute(1,2,0).cpu().numpy() to get (H, W, C)","Audit any np.squeeze/np.newaxis calls upstream that change rank"],"exampleFix":"# before\ngray = cv2.imread(p, cv2.IMREAD_GRAYSCALE)\nsession.face_detection(gray)\n# after\ngray = cv2.imread(p, cv2.IMREAD_GRAYSCALE)\nbgr = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)\nsession.face_detection(bgr)","handlingStrategy":"validation","validationCode":"assert isinstance(img, np.ndarray) and img.ndim == 3, f'need HWC, got {getattr(img, \"shape\", None)}'","typeGuard":"def is_hwc_image(img) -> bool:\n    import numpy as np\n    return isinstance(img, np.ndarray) and img.ndim == 3","tryCatchPattern":null,"preventionTips":["Normalize tensors: .permute(1,2,0).cpu().numpy()","Convert grayscale with cv2.cvtColor(..., GRAY2BGR) at load time"],"tags":["validation","image","shape","numpy"],"backgroundTag":"invalid-image-shape","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}