{"record":{"id":"7c743938c4cf73a0","repo":"deepinsight/insightface","slug":"session-parameter-must-be-sessioncustomparameter-o","errorCode":null,"errorMessage":"Session parameter must be SessionCustomParameter or int","messagePattern":"Session parameter must be SessionCustomParameter or int","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/inspireface.py","lineNumber":335,"sourceCode":"        self.multiple_faces = None\n        self.param = param\n        \n        # If InspireFace is not initialized, run launch() use Pikachu model\n        if not query_launch_status():\n            ret = launch()\n            if not ret:\n                raise SystemNotReadyError(\"Failed to launch InspireFace automatically\")\n\n        self._sess = HFSession()\n        \n        if isinstance(self.param, SessionCustomParameter):\n            ret = HFCreateInspireFaceSession(self.param._c_struct(), detect_mode, max_detect_num, detect_pixel_level,\n                                             track_by_detect_mode_fps, self._sess)\n        elif isinstance(self.param, int):\n            ret = HFCreateInspireFaceSessionOptional(self.param, detect_mode, max_detect_num, detect_pixel_level,\n                                                     track_by_detect_mode_fps, self._sess)\n        else:\n            raise InvalidInputError(\"Session parameter must be SessionCustomParameter or int\", \n                                   context={'param_type': type(self.param).__name__})\n        \n        check_error(ret, \"Create InspireFace session\", \n                   detect_mode=detect_mode, max_detect_num=max_detect_num)\n\n    @handle_c_api_errors(\"Face detection\")\n    def face_detection(self, image) -> List[FaceInformation]:\n        \"\"\"\n        Detects faces in the given image and returns a list of FaceInformation objects containing detailed face data.\n        \n        Args:\n            image (np.ndarray or ImageStream): The image in which to detect faces.\n            \n        Returns:\n            List[FaceInformation]: A list of detected face information.\n            \n        Raises:\n            ResourceError: If session is not initialized.","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/inspireface.py#L317-L353","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Pass SessionCustomParameter() (customize flags on it) or an int bitmask like 0 / HF_ENABLE_FACE_RECOGNITION","If building from config, map keys onto SessionCustomParameter fields explicitly"],"exampleFix":"# before\nsession = InspireFaceSession({'align_mode': 1})\n# after\nfrom inspireface.modules.core.session_param import SessionCustomParameter\nparam = SessionCustomParameter()\nparam.aligned_face = True\nsession = InspireFaceSession(param, detect_mode=0, max_detect_num=10)","handlingStrategy":"type-guard","validationCode":"from inspireface.modules.core.session_param import SessionCustomParameter\nassert isinstance(param, (SessionCustomParameter, int)) and not isinstance(param, bool), type(param)","typeGuard":"def is_valid_session_param(p) -> bool:\n    from inspireface.modules.core.session_param import SessionCustomParameter\n    return isinstance(p, (SessionCustomParameter, int)) and not isinstance(p, bool)","tryCatchPattern":null,"preventionTips":["Construct SessionCustomParameter() explicitly; never pass dicts from config","Reject bools — they subclass int and silently select bitmask mode"],"tags":["validation","constructor","session","type-error"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}