{"record":{"id":"9c5a15fc838ebe8e","repo":"blakeblackshear/frigate","slug":"failed-to-initialize-rknn-runtime","errorCode":null,"errorMessage":"Failed to initialize RKNN runtime","messagePattern":"Failed to initialize RKNN runtime","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"frigate/detectors/detection_runners.py","lineNumber":485,"sourceCode":"        self.model_type = model_type\n        self.core_mask = core_mask\n        self.rknn = None\n        self._load_model()\n\n    def _load_model(self):\n        \"\"\"Load the RKNN model.\"\"\"\n        try:\n            from rknnlite.api import RKNNLite\n\n            self.rknn = RKNNLite(verbose=False)\n\n            if self.rknn.load_rknn(self.model_path) != 0:\n                logger.error(f\"Failed to load RKNN model: {self.model_path}\")\n                raise RuntimeError(\"Failed to load RKNN model\")\n\n            if self.rknn.init_runtime(core_mask=self.core_mask) != 0:\n                logger.error(\"Failed to initialize RKNN runtime\")\n                raise RuntimeError(\"Failed to initialize RKNN runtime\")\n\n            logger.info(f\"Successfully loaded RKNN model: {self.model_path}\")\n\n        except ImportError:\n            logger.error(\"RKNN Lite not available\")\n            raise ImportError(\"RKNN Lite not available\") from None\n        except Exception as e:\n            logger.error(f\"Error loading RKNN model: {e}\")\n            raise\n\n    def get_input_names(self) -> list[str]:\n        \"\"\"Get input names for the model.\"\"\"\n        # For detection models, we typically use \"input\" as the default input name\n        # For CLIP models, we need to determine the model type from the path\n        model_name = os.path.basename(self.model_path).lower()\n\n        if \"vision\" in model_name:\n            return [\"pixel_values\"]","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/blakeblackshear/frigate/blob/ca18b8dc131ccb3e086f13a780853b775ef13426/frigate/detectors/detection_runners.py#L467-L503","documentation":"The RKNN runtime failed to initialize after the .rknn model file was successfully loaded. RKNNRuntimeLite.init_runtime returned a non-zero status, which usually means the NPU device is unavailable, the core_mask is invalid for the SoC, or the RKNN runtime version does not match the model/toolkit version. This is raised as RuntimeError from _load_model during detector __init__.","triggerScenarios":"Calling the RKNN detection runner's __init__ (which calls _load_model) where rknn.load_rknn succeeds but rknn.init_runtime(core_mask=self.core_mask) != 0. Happens on non-Rockchip hosts, wrong core_mask for the SoC (e.g. dual-core mask on single-core NPU), missing /dev/dri or NPU kernel driver, or rknn-toolkit-lite2 version mismatch with the model.","commonSituations":"Running the Frigate container without privileged mode / mapped NPU device on RK3588; using a model compiled with a newer rknn-toolkit2 than the installed rknn-toolkit-lite2; specifying core_mask=NPU_CORE_0_1 on an RK356x which has one NPU core; host librknnrt.so version mismatch.","solutions":["Verify the NPU is visible in the container (ls /dev/dri, dmesg | grep rknpu) and run Frigate with the device mapped and privileged mode enabled","Ensure the rknn-toolkit-lite2 and librknnrt.so runtime versions match the rknn-toolkit2 version used to convert the model (re-export or upgrade the runtime)","Set a core_mask valid for your SoC (single core masks like NPU_CORE_0 on RK356x; multi-core masks only on RK3588)","Re-convert the model with a matching toolkit version and confirm it initializes with the rknn_toolkit_lite2 python API directly on the device"],"exampleFix":"# before\ncore_mask: 3  # NPU_CORE_0_1, invalid on RK356x\n# after\ncore_mask: 0  # NPU_CORE_AUTO / single core for RK356x","handlingStrategy":"validation","validationCode":"import subprocess\n\ndef npu_available() -> bool:\n    try:\n        return subprocess.run(['cat','/sys/kernel/debug/rknpu/version'],capture_output=True).returncode == 0 or bool(__import__('glob').glob('/dev/dri/*'))\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    detector = LocalDetector(detector_config)\nexcept RuntimeError as e:\n    if 'initialize RKNN runtime' in str(e):\n        logger.error('RKNN NPU unavailable, check device mapping/core_mask/runtime version')\n    raise","preventionTips":["Run Frigate Rockchip images with the NPU devices mapped and privileged mode","Keep rknn-toolkit-lite2/librknnrt versions matched to the model conversion toolkit","Use core_mask values valid for the specific SoC"],"tags":["rknn","rockchip","npu","runtime-init","detector"],"backgroundTag":"npu-runtime-init-failed","analyzedSha":"ca18b8dc131ccb3e086f13a780853b775ef13426","analyzedAt":"2026-08-27T11:28:05.618Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}