deepinsight/insightface · error · InvalidInputError

HERR_INVALID_IMAGE_STREAM_PARAM

HERR_INVALID_IMAGE_STREAM_PARAM

Error message

{operation}: Image must be 3-dimensional (H, W, C)

What it means

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.

Source

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

    # Raise corresponding exception
    raise exception_class(message, error_code, **context)


# === Convenient validation functions ===

def validate_image_format(image, operation: str = "Image validation"):
    """Validate image format"""
    import numpy as np
    
    if not isinstance(image, np.ndarray):
        raise InvalidInputError(
            f"{operation}: Input must be a numpy array",
            errcode.HERR_INVALID_PARAM,
            input_type=type(image).__name__
        )
    
    if len(image.shape) != 3:
        raise InvalidInputError(
            f"{operation}: Image must be 3-dimensional (H, W, C)",
            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,
            actual_shape=image.shape
        )
    
    h, w, c = image.shape
    if c not in [3, 4]:
        raise InvalidInputError(
            f"{operation}: Image must have 3 or 4 channels",
            errcode.HERR_INVALID_IMAGE_STREAM_PARAM,
            actual_channels=c
        )


def validate_feature_data(data, operation: str = "Feature validation"):
    """Validate feature data format"""
    import numpy as np
    

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Grayscale: img = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
2. Tensor input: arr = tensor.squeeze(0).permute(1,2,0).cpu().numpy() to get (H, W, C)
3. Audit any np.squeeze/np.newaxis calls upstream that change rank

Example fix

# before
gray = cv2.imread(p, cv2.IMREAD_GRAYSCALE)
session.face_detection(gray)
# after
gray = cv2.imread(p, cv2.IMREAD_GRAYSCALE)
bgr = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
session.face_detection(bgr)

assert isinstance(img, np.ndarray) and img.ndim == 3, f'need HWC, got {getattr(img, "shape", None)}'

def is_hwc_image(img) -> bool:
    import numpy as np
    return isinstance(img, np.ndarray) and img.ndim == 3

When it happens

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

Common situations: Preprocessing pipelines that squeeze/expand dims, model-centric code assuming channel-first tensors, grayscale camera feeds converted without color conversion.

Related errors

• HERR_INVALID_PARAM
• HERR_INVALID_FACE_FEATURE
• Image must be numpy.ndarray or ImageStream
• Session parameter must be SessionCustomParameter or int
• exec_param must be SessionCustomParameter or int

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