deepinsight/insightface · critical · SystemNotReadyError

Failed to launch InspireFace automatically

Error message

Failed to launch InspireFace automatically

What it means

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.

Source

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

        Args:
            param (int or SessionCustomParameter): Configuration parameters or flags.
            detect_mode (int): Detection mode to be used (e.g., image-based detection).
            max_detect_num (int): Maximum number of faces to detect.
            
        Raises:
            SystemNotReadyError: If InspireFace is not launched.
            ProcessingError: If session creation fails.
        """
        # Initialize _sess to None first to prevent AttributeError in __del__
        self._sess = None
        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]:

View on GitHub (pinned to 7fadd420c2)

Solutions

1. Download/pre-place the resource pack and launch explicitly: inspireface.launch('/path/to/inspireface_res', enable_download=True), then construct the session
2. If offline, point launch() at an existing local resource directory (no download needed)
3. Verify the resource directory actually contains the pikachu model files and is readable by the process
4. Check the preceding native log output for the concrete launch failure reason

Example fix

# before
session = InspireFaceSession(SessionCustomParameter())  # SystemNotReadyError
# after
import inspireface
inspireface.launch('/abs/path/inspireface_res', enable_download=True)
session = InspireFaceSession(SessionCustomParameter())

import inspireface
if not inspireface.query_launch_status():
    inspireface.launch('/abs/path/inspireface_res', enable_download=True)

from inspireface.modules.exception import SystemNotReadyError
try:
    session = InspireFaceSession(param)
except SystemNotReadyError:
    inspireface.launch(res_path, enable_download=True)
    session = InspireFaceSession(param)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• HERR_INVALID_CONTEXT_HANDLE
• Unsupported platform: system={system}, machine={machine}
• Library not found at {lib_path}. System: {system}, Architect
• HERR_INVALID_PARAM
• HERR_INVALID_FACE_FEATURE

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