deepinsight/insightface · error · InvalidInputError

Session parameter must be SessionCustomParameter or int

Error message

Session parameter must be SessionCustomParameter or int

What it means

InspireFaceSession.__init__ accepts param as either a SessionCustomParameter (rendered via _c_struct() into HFCreateInspireFaceSession) or an int bitmask (passed to HFCreateInspireFaceSessionOptional). Any other type raises InvalidInputError naming the actual param_type.

Source

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

        self.multiple_faces = None
        self.param = param
        
        # If InspireFace is not initialized, run launch() use Pikachu model
        if not query_launch_status():
            ret = launch()
            if not ret:
                raise SystemNotReadyError("Failed to launch InspireFace automatically")

        self._sess = HFSession()
        
        if isinstance(self.param, SessionCustomParameter):
            ret = HFCreateInspireFaceSession(self.param._c_struct(), detect_mode, max_detect_num, detect_pixel_level,
                                             track_by_detect_mode_fps, self._sess)
        elif isinstance(self.param, int):
            ret = HFCreateInspireFaceSessionOptional(self.param, detect_mode, max_detect_num, detect_pixel_level,
                                                     track_by_detect_mode_fps, self._sess)
        else:
            raise InvalidInputError("Session parameter must be SessionCustomParameter or int", 
                                   context={'param_type': type(self.param).__name__})
        
        check_error(ret, "Create InspireFace session", 
                   detect_mode=detect_mode, max_detect_num=max_detect_num)

    @handle_c_api_errors("Face detection")
    def face_detection(self, image) -> List[FaceInformation]:
        """
        Detects faces in the given image and returns a list of FaceInformation objects containing detailed face data.
        
        Args:
            image (np.ndarray or ImageStream): The image in which to detect faces.
            
        Returns:
            List[FaceInformation]: A list of detected face information.
            
        Raises:
            ResourceError: If session is not initialized.

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Pass SessionCustomParameter() (customize flags on it) or an int bitmask like 0 / HF_ENABLE_FACE_RECOGNITION
2. If building from config, map keys onto SessionCustomParameter fields explicitly

Example fix

# before
session = InspireFaceSession({'align_mode': 1})
# after
from inspireface.modules.core.session_param import SessionCustomParameter
param = SessionCustomParameter()
param.aligned_face = True
session = InspireFaceSession(param, detect_mode=0, max_detect_num=10)

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

def is_valid_session_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: Passing a dict, string, HFSession, None, or a bool instead of SessionCustomParameter/int when constructing InspireFaceSession; also passing a custom-enum object that isn't a plain int.

Common situations: Copy-pasting older examples where a string enum was accepted; building the param from JSON config as a dict; assuming a default exists (there is none — you must pass one of the two types).

Related errors

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

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