immich-app/immich · error · ValueError

model_path must point to an existing file!

Error message

model_path must point to an existing file!

What it means

Raised by Ann.load() immediately after the extension check, when os.path.exists(model_path) is False. The extension was acceptable but the file is not on disk at the given location. Unlike [240] (which uses Path.is_file and goes through the high-level model loader), this is the lower-level Ann.load guard for direct callers.

Source

Thrown at machine-learning/immich_ml/sessions/ann/loader.py:107

            libann.destroy(self.ann)
            self.ann = None

    def __del__(self) -> None:
        if self.ann is not None:
            libann.destroy(self.ann)
            self.ann = None

    def load(
        self,
        model_path: str,
        fast_math: bool = True,
        fp16: bool = False,
        cached_network_path: str | None = None,
    ) -> int:
        if not model_path.endswith((".armnn", ".tflite", ".onnx")):
            raise ValueError("model_path must be a file with extension .armnn, .tflite or .onnx")
        if not exists(model_path):
            raise ValueError("model_path must point to an existing file!")

        save_cached_network = False
        if cached_network_path is not None and not exists(cached_network_path):
            save_cached_network = True
            # create empty model cache file
            open(cached_network_path, "a").close()

        net_id: int = libann.load(
            self.ann,
            model_path.encode(),
            fast_math,
            fp16,
            save_cached_network,
            cached_network_path.encode() if cached_network_path is not None else None,
        )
        if net_id < 0:
            raise ValueError("Cannot load model!")

View on GitHub (pinned to 199723261c)

Solutions

1. Verify the file exists at the exact absolute path in the error using `ls -l`.
2. Ensure the download/copy step that produces the model file completed before Ann.load is called.
3. Use an absolute path; if you must use a relative one, confirm the process working directory.
4. Check container volume mounts and that the model directory is mounted read/write as needed.
5. Confirm the current user has read permission on the file and traverse permission on its parent directories.

Example fix

# before
ann.load('/data/models/model.armnn')   # ValueError: must point to an existing file
# (file was never copied into the container)

# after
# docker-compose volume mount exposes the file
ann.load('/models/model.armnn')
# or guard before calling:
from os.path import exists
if not exists(model_path):
    raise FileNotFoundError(model_path)

from os.path import exists, isfile

def validate_armnn_file_exists(model_path: str) -> None:
    if not (exists(model_path) and isfile(model_path)):
        raise FileNotFoundError(f"{model_path} does not exist or is not a regular file")

# call before Ann.load():
validate_armnn_file_exists(model_path)

from os.path import isfile

def is_armnn_file_present(model_path: str) -> bool:
    return isinstance(model_path, str) and isfile(model_path)

try:
    net_id = ann.load(model_path)
except ValueError as e:
    if 'existing file' in str(e):
        raise FileNotFoundError(model_path) from e
    raise

When it happens

Trigger: Calling Ann.load() with a well-formed path to a file that has not been downloaded/copied yet, that lives on an unmounted volume, or whose parent directory was cleaned. Also triggered by relative paths resolved against an unexpected working directory.

Common situations: Model download step failed or was skipped before invoking Ann.load; volume mount missing in the container; path typo or wrong model_dir; running as a user without read permission on the file (exists() returns False for unreadable parent in some setups); race where the file is still being written.

Related errors

• Invalid import path: ${path.message}
• model_path must be a file with extension .armnn, .tflite or
• Failed to read helmet file: ${helmetFile}
• Invalid environment variables: \n - [${path}] ${issue.messa
• Invalid worker(s) found: ${workers.join(',')}

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