immich-app/immich · critical · RuntimeError

rknn is not available!

Error message

rknn is not available!

What it means

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__.

Source

Thrown at machine-learning/immich_ml/sessions/rknn/rknnpool.py:43

    except OSError as e:
        log.warning(f"Could not read {device_tree_path}. Reason: %s", e)
    return None


soc_name = None
is_available = False
try:
    from rknnlite.api import RKNNLite

    soc_name = get_soc("/proc/device-tree/compatible")
    is_available = soc_name is not None
except ImportError:
    log.debug("RKNN is not available")


def init_rknn(model_path: str) -> "RKNNLite":
    if not is_available:
        raise RuntimeError("rknn is not available!")
    rknn_lite = RKNNLite()
    rknn_lite.rknn_log.logger.setLevel(logging.ERROR)
    ret = rknn_lite.load_rknn(model_path)
    if ret != 0:
        raise RuntimeError("Failed to load RKNN model")

    if soc_name in RKNN_COREMASK_SUPPORTED_SOCS:
        ret = rknn_lite.init_runtime(core_mask=RKNNLite.NPU_CORE_AUTO)
    else:
        ret = rknn_lite.init_runtime()  # Please do not set this parameter on other platforms.

    if ret != 0:
        raise RuntimeError("Failed to initialize RKNN runtime environment")

    return rknn_lite


class RknnPoolExecutor:

View on GitHub (pinned to 199723261c)

Solutions

1. Confirm you are on a supported Rockchip SoC and using the immich-ml RKNN image variant.
2. Install rknnlite (`pip install rknnlite` matching your SoC's runtime package) and ensure /proc is mounted in the container.
3. 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.
4. If your SoC is new, add it to RKNN_SUPPORTED_SOCS in immich_ml/models/constants.py and confirm get_soc returns it.
5. Switch to ONNX/ARMNN model_format if you are not actually on a Rockchip NPU platform.

Example fix

# before
# stock CPU image, no rknnlite -> is_available=False
session = RknnSession(Path('/models/model.rknn'))   # RuntimeError: rknn is not available!

# after
# use the RKNN image variant and set the flag
#   image: ghcr.io/immich-app/immich-machine-learning:rknn
#   environment:
#     RKNN: true
session = RknnSession(Path('/models/model.rknn'))

from immich_ml.sessions.rknn import is_available as rknn_available

def ensure_rknn_available() -> None:
    if not rknn_available:
        raise RuntimeError(
            "RKNN unavailable: install rknnlite, run on a supported Rockchip SoC, "
            "set the RKNN setting, and mount /proc. Falling back to ONNX is recommended otherwise."
        )

# call before constructing RknnSession:
ensure_rknn_available()

from immich_ml.sessions.rknn import is_available

def rknn_runtime_available() -> bool:
    return bool(is_available)

from immich_ml.sessions.rknn import is_available
try:
    session = RknnSession(model_path)
except RuntimeError as e:
    if not is_available:
        log.warning("RKNN unavailable; falling back to ONNX session")
        session = OrtSession(model_path.with_suffix('.onnx'))
    else:
        raise

When it happens

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

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

Related errors

• Failed to initialize RKNN runtime environment
• RKNN inference failed!
• Failed to load RKNN model
• libann is not available!
• Cannot load model!

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/723f8906baf2f984. Report an issue: GitHub.