{"record":{"id":"723f8906baf2f984","repo":"immich-app/immich","slug":"rknn-is-not-available","errorCode":null,"errorMessage":"rknn is not available!","messagePattern":"rknn is not available!","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"machine-learning/immich_ml/sessions/rknn/rknnpool.py","lineNumber":43,"sourceCode":"    except OSError as e:\n        log.warning(f\"Could not read {device_tree_path}. Reason: %s\", e)\n    return None\n\n\nsoc_name = None\nis_available = False\ntry:\n    from rknnlite.api import RKNNLite\n\n    soc_name = get_soc(\"/proc/device-tree/compatible\")\n    is_available = soc_name is not None\nexcept ImportError:\n    log.debug(\"RKNN is not available\")\n\n\ndef init_rknn(model_path: str) -> \"RKNNLite\":\n    if not is_available:\n        raise RuntimeError(\"rknn is not available!\")\n    rknn_lite = RKNNLite()\n    rknn_lite.rknn_log.logger.setLevel(logging.ERROR)\n    ret = rknn_lite.load_rknn(model_path)\n    if ret != 0:\n        raise RuntimeError(\"Failed to load RKNN model\")\n\n    if soc_name in RKNN_COREMASK_SUPPORTED_SOCS:\n        ret = rknn_lite.init_runtime(core_mask=RKNNLite.NPU_CORE_AUTO)\n    else:\n        ret = rknn_lite.init_runtime()  # Please do not set this parameter on other platforms.\n\n    if ret != 0:\n        raise RuntimeError(\"Failed to initialize RKNN runtime environment\")\n\n    return rknn_lite\n\n\nclass RknnPoolExecutor:","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/immich-app/immich/blob/199723261c6ffa897fec8ccdaea6359e39c37cc3/machine-learning/immich_ml/sessions/rknn/rknnpool.py#L25-L61","documentation":"Raised by init_rknn() when the module-level is_available flag is False. is_available is False when either `from rknnlite.api import RKNNLite` raised ImportError (rknnlite package not installed) or get_soc('/proc/device-tree/compatible') returned None (the running SoC is not in RKNN_SUPPORTED_SOCS). The flag is also gated by settings.rknn in the package __init__.","triggerScenarios":"Calling RknnPoolExecutor(...) / RknnSession(...) on a host without the rknnlite Python package installed, or on a device whose /proc/device-tree/compatible does not list a supported Rockchip SoC, or with settings.rknn disabled. init_rknn is invoked once per worker thread during RknnPoolExecutor construction.","commonSituations":"Running the immich-ml CPU/GPU image instead of the RKNN image on a Rockchip board; rknnlite not installed in the venv; /proc/device-tree/compatible unreadable in a container (proc not mounted, or running in a non-ARM VM); supported-SoC list out of date for a newer Rockchip chip; settings.rknn=False by default because the env var was not set.","solutions":["Confirm you are on a supported Rockchip SoC and using the immich-ml RKNN image variant.","Install rknnlite (`pip install rknnlite` matching your SoC's runtime package) and ensure /proc is mounted in the container.","Set the env var that enables settings.rknn (e.g. RKNN flag in immich_ml config) so the __init__ gate does not force is_available False.","If your SoC is new, add it to RKNN_SUPPORTED_SOCS in immich_ml/models/constants.py and confirm get_soc returns it.","Switch to ONNX/ARMNN model_format if you are not actually on a Rockchip NPU platform."],"exampleFix":"# before\n# stock CPU image, no rknnlite -> is_available=False\nsession = RknnSession(Path('/models/model.rknn'))   # RuntimeError: rknn is not available!\n\n# after\n# use the RKNN image variant and set the flag\n#   image: ghcr.io/immich-app/immich-machine-learning:rknn\n#   environment:\n#     RKNN: true\nsession = RknnSession(Path('/models/model.rknn'))","handlingStrategy":"type-guard","validationCode":"from immich_ml.sessions.rknn import is_available as rknn_available\n\ndef ensure_rknn_available() -> None:\n    if not rknn_available:\n        raise RuntimeError(\n            \"RKNN unavailable: install rknnlite, run on a supported Rockchip SoC, \"\n            \"set the RKNN setting, and mount /proc. Falling back to ONNX is recommended otherwise.\"\n        )\n\n# call before constructing RknnSession:\nensure_rknn_available()","typeGuard":"from immich_ml.sessions.rknn import is_available\n\ndef rknn_runtime_available() -> bool:\n    return bool(is_available)","tryCatchPattern":"from immich_ml.sessions.rknn import is_available\ntry:\n    session = RknnSession(model_path)\nexcept RuntimeError as e:\n    if not is_available:\n        log.warning(\"RKNN unavailable; falling back to ONNX session\")\n        session = OrtSession(model_path.with_suffix('.onnx'))\n    else:\n        raise","preventionTips":["Use the immich-ml RKNN image variant on Rockchip boards; do not enable settings.rknn elsewhere.","Mount /proc and pass through NPU devices in the container spec.","When supporting a new SoC, add it to RKNN_SUPPORTED_SOCS and gate model_prefix accordingly."],"tags":["rknn","npu","rockchip","native-library","container"],"backgroundTag":null,"analyzedSha":"199723261c6ffa897fec8ccdaea6359e39c37cc3","analyzedAt":"2026-08-12T04:54:27.085Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}