ultralytics/ultralytics · error · RuntimeError

Failed to load RKNN model: {ret}

Error message

Failed to load RKNN model: {ret}

What it means

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.

Source

Thrown at ultralytics/nn/backends/rknn.py:46

        Raises:
            OSError: If not running on a Rockchip device.
            RuntimeError: If model loading or runtime initialization fails.
        """
        if not is_rockchip():
            raise OSError("RKNN inference is only supported on Rockchip devices.")

        LOGGER.info(f"Loading {weight} for RKNN inference...")
        check_requirements("rknn-toolkit-lite2")
        from rknnlite.api import RKNNLite

        w = Path(weight)
        if not w.is_file():
            w = next(w.rglob("*.rknn"))

        self.model = RKNNLite()
        ret = self.model.load_rknn(str(w))
        if ret != 0:
            raise RuntimeError(f"Failed to load RKNN model: {ret}")

        ret = self.model.init_runtime()
        if ret != 0:
            raise RuntimeError(f"Failed to init RKNN runtime: {ret}")

        # Load metadata
        metadata_file = w.parent / "metadata.yaml"
        if metadata_file.exists():
            from ultralytics.utils import YAML

            self.apply_metadata(YAML.load(metadata_file))

    def forward(self, im: torch.Tensor) -> list:
        """Run inference on the Rockchip NPU.

        Args:
            im (torch.Tensor): Input image tensor in BHWC format, normalized to [0, 1].

View on GitHub (pinned to 0449ea011c)

Solutions

1. 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).
2. Verify file integrity: compare md5sum of the .rknn on the converter and the device; re-transfer if it differs or the size looks short.
3. 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.

Example fix

# before: model converted with rknn-toolkit2==1.5, device runs rknn-toolkit-lite2==2.3
# RuntimeError: Failed to load RKNN model: -1

# after: align versions
# pip install rknn-toolkit2==2.3.0  (on converter PC)
yolo export model=yolo26n.pt format=rknn
# device: pip install rknn-toolkit-lite2==2.3.0

from pathlib import Path

p = Path(rknn_file)
assert 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)'
# compare checksum against the converter machine's record
import hashlib
assert hashlib.md5(p.read_bytes()).hexdigest() == EXPECTED_MD5, 'rknn file corrupted in transfer'

try:
    model = YOLO(rknn_path)
except RuntimeError as e:
    if 'Failed to load RKNN model' in str(e):
        logger.error('Ret code %s — re-convert with a rknn-toolkit2 version matching on-device rknn-toolkit-lite2', e)
        raise

When it happens

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

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

Related errors

• Failed to init RKNN runtime: {ret}
• Rockchip target '{}' only supports INT8, but got quantize={}
• RKNN inference is only supported on Rockchip devices.
• RKNN {name} failed with return code {ret}.
• Rockchip target '{name}' requires quantize=8. Use a target t

AI-assisted analysis of ultralytics/ultralytics@0449ea011c (2026-08-15). Data as JSON: /api/errors/07532a8f50cab2b7. Report an issue: GitHub.