What causes "{operation}: Input must be a numpy array" in deepinsight/insightface?

Convert first: np_img = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR) or load with cv2.imread(path)

deepinsight/insightface · error · InvalidInputError

HERR_INVALID_PARAM

HERR_INVALID_PARAM

Error message

{operation}: Input must be a numpy array

What it means

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.

Source

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

                exception_class = ResourceError
            elif category == 'hardware':
                exception_class = HardwareError
            elif category == 'feature_hub':
                exception_class = FeatureHubError
            break
    
    # 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

View on GitHub (pinned to 7fadd420c2)

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)

Example fix

# before
img = Image.open('a.jpg')
session.face_detection(img)
# after
import cv2, numpy as np
img = cv2.cvtColor(np.array(Image.open('a.jpg')), cv2.COLOR_RGB2BGR)
session.face_detection(img)

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np
def as_bgr_ndarray(img):
    if not isinstance(img, np.ndarray):
        import cv2
        img = cv2.cvtColor(np.asarray(img), cv2.COLOR_RGB2BGR)
    return img

Type guard

def is_valid_image(img) -> bool:
    import numpy as np
    return isinstance(img, np.ndarray)

Try / catch

from inspireface.modules.exception import InvalidInputError
try:
    session.face_detection(img)
except InvalidInputError as e:
    raise TypeError('convert image to BGR ndarray first') from e

Prevention

Standardize on cv2.imread at your pipeline entry
Check cv2.imread result for None before passing downstream

When it happens

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

Common situations: 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.

Related errors

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