{"record":{"id":"42f3370e78c71172","repo":"deepinsight/insightface","slug":"exec-param-must-be-sessioncustomparameter-or-int","errorCode":null,"errorMessage":"exec_param must be SessionCustomParameter or int","messagePattern":"exec_param must be SessionCustomParameter or int","errorType":"validation","errorClass":"InvalidInputError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/inspireface.py","lineNumber":579,"sourceCode":"    def _get_image_stream(image):\n        \"\"\"Convert image to ImageStream if needed\"\"\"\n        if isinstance(image, np.ndarray):\n            return ImageStream.load_from_cv_image(image)\n        elif isinstance(image, ImageStream):\n            return image\n        else:\n            raise InvalidInputError(\"Image must be numpy.ndarray or ImageStream\", \n                                   context={'input_type': type(image).__name__})\n\n    @staticmethod\n    def _get_processing_function_and_param(exec_param):\n        \"\"\"Get processing function and parameters\"\"\"\n        if isinstance(exec_param, SessionCustomParameter):\n            return HFMultipleFacePipelineProcess, exec_param._c_struct(), \"object\"\n        elif isinstance(exec_param, int):\n            return HFMultipleFacePipelineProcessOptional, exec_param, \"bitmask\"\n        else:\n            raise InvalidInputError(\"exec_param must be SessionCustomParameter or int\",\n                                   context={'param_type': type(exec_param).__name__})\n\n    def _update_mask_confidence(self, exec_param, flag, extends):\n        \"\"\"Update mask confidence in extends list\"\"\"\n        if (flag == \"object\" and exec_param.enable_mask_detect) or (\n                flag == \"bitmask\" and exec_param & HF_ENABLE_MASK_DETECT):\n            mask_results = HFFaceMaskConfidence()\n            ret = HFGetFaceMaskConfidence(self._sess, PHFFaceMaskConfidence(mask_results))\n            if ret == errcode.HSUCCEED:\n                for i in range(mask_results.num):\n                    extends[i].mask_confidence = mask_results.confidence[i]\n            else:\n                logger.warning(f\"Failed to get mask confidence: error code {ret}\")\n\n    def _update_face_interact_confidence(self, exec_param, flag, extends):\n        \"\"\"Update face interaction confidence in extends list\"\"\"\n        if (flag == \"object\" and exec_param.enable_interaction_liveness) or (\n                flag == \"bitmask\" and exec_param & HF_ENABLE_INTERACTION):","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/inspireface.py#L561-L597","documentation":"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.","triggerScenarios":"Calling face_pipeline(image, exec_param=<dict|str|None|list>) with anything but a SessionCustomParameter instance or an int bitmask.","commonSituations":"Config-driven code passing raw JSON values; passing the HF_ENABLE_* constants as strings; refactors that changed the parameter type without updating call sites.","solutions":["Use the session's own param: face_pipeline(img, session.param) when param was a SessionCustomParameter","Or pass an int bitmask, e.g. HF_ENABLE_FACE_RECOGNITION | HF_ENABLE_MASK_DETECT (or 0)","Validate isinstance(exec_param, (SessionCustomParameter, int)) at your call boundary"],"exampleFix":"# before\nresult = session.face_pipeline(img, exec_param='all')\n# after\nfrom inspireface.modules.inspireface import HF_ENABLE_MASK_DETECT\nresult = session.face_pipeline(img, exec_param=HF_ENABLE_MASK_DETECT)\n# or: result = session.face_pipeline(img, exec_param=session.param)","handlingStrategy":"type-guard","validationCode":"from inspireface.modules.core.session_param import SessionCustomParameter\nassert isinstance(exec_param, (SessionCustomParameter, int)) and not isinstance(exec_param, bool), type(exec_param)","typeGuard":"def is_valid_exec_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":["Pass session.param through, or compose HF_ENABLE_* int constants","Map config dicts onto SessionCustomParameter fields before calling face_pipeline"],"tags":["validation","pipeline","bitmask","inspireface"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}