deepinsight/insightface · error · InvalidInputError

exec_param must be SessionCustomParameter or int

Error message

exec_param must be SessionCustomParameter or int

What it means

InspireFaceSession._get_processing_function_and_param maps exec_param to either HFMultipleFacePipelineProcess (SessionCustomParameter → 'object' mode) or HFMultipleFacePipelineProcessOptional (int bitmask → 'bitmask' mode); any other type raises InvalidInputError before face_pipeline runs mask/attribute postprocessing.

Source

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

    def _get_image_stream(image):
        """Convert image to ImageStream if needed"""
        if isinstance(image, np.ndarray):
            return ImageStream.load_from_cv_image(image)
        elif isinstance(image, ImageStream):
            return image
        else:
            raise InvalidInputError("Image must be numpy.ndarray or ImageStream", 
                                   context={'input_type': type(image).__name__})

    @staticmethod
    def _get_processing_function_and_param(exec_param):
        """Get processing function and parameters"""
        if isinstance(exec_param, SessionCustomParameter):
            return HFMultipleFacePipelineProcess, exec_param._c_struct(), "object"
        elif isinstance(exec_param, int):
            return HFMultipleFacePipelineProcessOptional, exec_param, "bitmask"
        else:
            raise InvalidInputError("exec_param must be SessionCustomParameter or int",
                                   context={'param_type': type(exec_param).__name__})

    def _update_mask_confidence(self, exec_param, flag, extends):
        """Update mask confidence in extends list"""
        if (flag == "object" and exec_param.enable_mask_detect) or (
                flag == "bitmask" and exec_param & HF_ENABLE_MASK_DETECT):
            mask_results = HFFaceMaskConfidence()
            ret = HFGetFaceMaskConfidence(self._sess, PHFFaceMaskConfidence(mask_results))
            if ret == errcode.HSUCCEED:
                for i in range(mask_results.num):
                    extends[i].mask_confidence = mask_results.confidence[i]
            else:
                logger.warning(f"Failed to get mask confidence: error code {ret}")

    def _update_face_interact_confidence(self, exec_param, flag, extends):
        """Update face interaction confidence in extends list"""
        if (flag == "object" and exec_param.enable_interaction_liveness) or (
                flag == "bitmask" and exec_param & HF_ENABLE_INTERACTION):

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Use the session's own param: face_pipeline(img, session.param) when param was a SessionCustomParameter
2. Or pass an int bitmask, e.g. HF_ENABLE_FACE_RECOGNITION | HF_ENABLE_MASK_DETECT (or 0)
3. Validate isinstance(exec_param, (SessionCustomParameter, int)) at your call boundary

Example fix

# before
result = session.face_pipeline(img, exec_param='all')
# after
from inspireface.modules.inspireface import HF_ENABLE_MASK_DETECT
result = session.face_pipeline(img, exec_param=HF_ENABLE_MASK_DETECT)
# or: result = session.face_pipeline(img, exec_param=session.param)

from inspireface.modules.core.session_param import SessionCustomParameter
assert isinstance(exec_param, (SessionCustomParameter, int)) and not isinstance(exec_param, bool), type(exec_param)

def is_valid_exec_param(p) -> bool:
    from inspireface.modules.core.session_param import SessionCustomParameter
    return isinstance(p, (SessionCustomParameter, int)) and not isinstance(p, bool)

When it happens

Trigger: Calling face_pipeline(image, exec_param=<dict|str|None|list>) with anything but a SessionCustomParameter instance or an int bitmask.

Common situations: Config-driven code passing raw JSON values; passing the HF_ENABLE_* constants as strings; refactors that changed the parameter type without updating call sites.

Related errors

• HERR_INVALID_PARAM
• HERR_INVALID_FACE_FEATURE
• Image must be numpy.ndarray or ImageStream
• Model '{name}' not found. Available models: {list(self._MODE
• Unsupported platform: system={system}, machine={machine}

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