{"record":{"id":"61d5a95ca04aacdd","repo":"deepinsight/insightface","slug":"failed-to-launch-inspireface-automatically","errorCode":null,"errorMessage":"Failed to launch InspireFace automatically","messagePattern":"Failed to launch InspireFace automatically","errorType":"exception","errorClass":"SystemNotReadyError","httpStatus":null,"severity":"critical","filePath":"cpp-package/inspireface/python/inspireface/modules/inspireface.py","lineNumber":324,"sourceCode":"        Args:\n            param (int or SessionCustomParameter): Configuration parameters or flags.\n            detect_mode (int): Detection mode to be used (e.g., image-based detection).\n            max_detect_num (int): Maximum number of faces to detect.\n            \n        Raises:\n            SystemNotReadyError: If InspireFace is not launched.\n            ProcessingError: If session creation fails.\n        \"\"\"\n        # Initialize _sess to None first to prevent AttributeError in __del__\n        self._sess = None\n        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]:","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/inspireface.py#L306-L342","documentation":"InspireFaceSession.__init__ checks query_launch_status(); if the SDK isn't launched it calls the parameter-free launch() (which uses the default Pikachu model), and when that returns failure it raises SystemNotReadyError. It means the global native context could not be initialized, usually because the default model resource isn't present or loadable.","triggerScenarios":"Constructing InspireFaceSession without calling inspireface.launch(resource_path, enable_download) first, on a machine where the default bundled model is missing, corrupted, or unreadable, so automatic launch fails.","commonSituations":"Fresh installs where the resource pack wasn't downloaded; docker images that exclude the resource directory; moving/deleting the downloaded model cache; running offline with no pre-downloaded resource.","solutions":["Download/pre-place the resource pack and launch explicitly: inspireface.launch('/path/to/inspireface_res', enable_download=True), then construct the session","If offline, point launch() at an existing local resource directory (no download needed)","Verify the resource directory actually contains the pikachu model files and is readable by the process","Check the preceding native log output for the concrete launch failure reason"],"exampleFix":"# before\nsession = InspireFaceSession(SessionCustomParameter())  # SystemNotReadyError\n# after\nimport inspireface\ninspireface.launch('/abs/path/inspireface_res', enable_download=True)\nsession = InspireFaceSession(SessionCustomParameter())","handlingStrategy":"try-catch","validationCode":"import inspireface\nif not inspireface.query_launch_status():\n    inspireface.launch('/abs/path/inspireface_res', enable_download=True)","typeGuard":null,"tryCatchPattern":"from inspireface.modules.exception import SystemNotReadyError\ntry:\n    session = InspireFaceSession(param)\nexcept SystemNotReadyError:\n    inspireface.launch(res_path, enable_download=True)\n    session = InspireFaceSession(param)","preventionTips":["Call inspireface.launch(resource_path) explicitly at app startup instead of relying on auto-launch","Bake the resource pack into Docker images for offline deployments"],"tags":["initialization","resource","model","inspireface"],"backgroundTag":"sdk-not-launched","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}