{"record":{"id":"07532a8f50cab2b7","repo":"ultralytics/ultralytics","slug":"failed-to-load-rknn-model-ret","errorCode":null,"errorMessage":"Failed to load RKNN model: {ret}","messagePattern":"Failed to load RKNN model: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"ultralytics/nn/backends/rknn.py","lineNumber":46,"sourceCode":"        Raises:\n            OSError: If not running on a Rockchip device.\n            RuntimeError: If model loading or runtime initialization fails.\n        \"\"\"\n        if not is_rockchip():\n            raise OSError(\"RKNN inference is only supported on Rockchip devices.\")\n\n        LOGGER.info(f\"Loading {weight} for RKNN inference...\")\n        check_requirements(\"rknn-toolkit-lite2\")\n        from rknnlite.api import RKNNLite\n\n        w = Path(weight)\n        if not w.is_file():\n            w = next(w.rglob(\"*.rknn\"))\n\n        self.model = RKNNLite()\n        ret = self.model.load_rknn(str(w))\n        if ret != 0:\n            raise RuntimeError(f\"Failed to load RKNN model: {ret}\")\n\n        ret = self.model.init_runtime()\n        if ret != 0:\n            raise RuntimeError(f\"Failed to init RKNN runtime: {ret}\")\n\n        # Load metadata\n        metadata_file = w.parent / \"metadata.yaml\"\n        if metadata_file.exists():\n            from ultralytics.utils import YAML\n\n            self.apply_metadata(YAML.load(metadata_file))\n\n    def forward(self, im: torch.Tensor) -> list:\n        \"\"\"Run inference on the Rockchip NPU.\n\n        Args:\n            im (torch.Tensor): Input image tensor in BHWC format, normalized to [0, 1].\n","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/ultralytics/ultralytics/blob/0449ea011cfd6c9a0d50a0bf1043aca5190cd476/ultralytics/nn/backends/rknn.py#L28-L64","documentation":"After locating the .rknn file, the backend calls RKNNLite.load_rknn() and inspects its integer return code; any non-zero code becomes RuntimeError('Failed to load RKNN model: <ret>'). RKNN uses C-style return codes rather than exceptions, so the number is your only diagnostic — commonly it indicates a corrupted file or a model compiled with an incompatible toolkit version/target.","triggerScenarios":"load_rknn() returns non-zero when the .rknn is truncated (bad transfer), was compiled by a rknn-toolkit2 version whose model format differs from the installed rknn-toolkit-lite2, or the file is not an RKNN model at all.","commonSituations":"Toolkit version skew between conversion PC (rknn-toolkit2) and device (rknn-toolkit-lite2); scp of the .rknn interrupted; model compiled for a different Rockchip SoC; exporting with a much older Ultralytics/toolkit and deploying with a newer runtime.","solutions":["Match versions: re-convert the model with an rknn-toolkit2 version compatible with the rknn-toolkit-lite2 on the device (check Rockchip's version-mapping table).","Verify file integrity: compare md5sum of the .rknn on the converter and the device; re-transfer if it differs or the size looks short.","Confirm the model was compiled for this exact SoC (target_platform matching, e.g. rk3588 vs rk3566); re-export if not: yolo export model=yolo26n.pt format=rknn."],"exampleFix":"# before: model converted with rknn-toolkit2==1.5, device runs rknn-toolkit-lite2==2.3\n# RuntimeError: Failed to load RKNN model: -1\n\n# after: align versions\n# pip install rknn-toolkit2==2.3.0  (on converter PC)\nyolo export model=yolo26n.pt format=rknn\n# device: pip install rknn-toolkit-lite2==2.3.0","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\n\np = Path(rknn_file)\nassert p.is_file() and p.stat().st_size > 1_000_000, f'{p} looks truncated ({p.stat().st_size if p.exists() else 0} bytes)'\n# compare checksum against the converter machine's record\nimport hashlib\nassert hashlib.md5(p.read_bytes()).hexdigest() == EXPECTED_MD5, 'rknn file corrupted in transfer'","typeGuard":null,"tryCatchPattern":"try:\n    model = YOLO(rknn_path)\nexcept RuntimeError as e:\n    if 'Failed to load RKNN model' in str(e):\n        logger.error('Ret code %s — re-convert with a rknn-toolkit2 version matching on-device rknn-toolkit-lite2', e)\n        raise","preventionTips":["Pin and document matching rknn-toolkit2 (converter) and rknn-toolkit-lite2 (device) versions.","Checksum .rknn files after transfer to the board."],"tags":["rknn","rockchip","runtime-error","version-mismatch","npu","export"],"backgroundTag":null,"analyzedSha":"0449ea011cfd6c9a0d50a0bf1043aca5190cd476","analyzedAt":"2026-08-15T02:34:13.413Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}