immich-app/immich · error · HTTPException

Failed to load model '{model.model_name}'

Error message

Failed to load model '{model.model_name}'

What it means

Raised as HTTPException(500) by the load() helper in main.py when a model fails to load more than once (model.load_attempts > 1). The first failure triggers a fallback: if the model is not ONNX format, it retries with ONNX; the second consecutive failure is treated as a hard error.

Source

Thrown at machine-learning/immich_ml/main.py:228

        response["imageHeight"], response["imageWidth"] = payload.height, payload.width

    return response


async def run(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
    if thread_pool is None:
        return func(*args, **kwargs)
    partial_func = partial(func, *args, **kwargs)
    return await asyncio.get_running_loop().run_in_executor(thread_pool, partial_func)


async def load(model: InferenceModel) -> InferenceModel:
    if model.loaded:
        return model

    def _load(model: InferenceModel) -> InferenceModel:
        if model.load_attempts > 1:
            raise HTTPException(500, f"Failed to load model '{model.model_name}'")
        with lock:
            try:
                model.load()
            except FileNotFoundError as e:
                if model.model_format == ModelFormat.ONNX:
                    raise e
                log.warning(
                    f"{model.model_format.upper()} is available, but model '{model.model_name}' does not support it.",
                    exc_info=e,
                )
                model.model_format = ModelFormat.ONNX
                model.load()
        return model

    try:
        return await run(_load, model)
    except (OSError, InvalidProtobuf, BadZipFile, NoSuchFile):
        log.warning(f"Failed to load {model.model_type.replace('_', ' ')} model '{model.model_name}'. Clearing cache.")

View on GitHub (pinned to 199723261c)

Solutions

1. Clear the ML model cache so models re-download fresh.
2. Check ML container logs for the underlying error (OOM, FileNotFoundError, provider errors).
3. Ensure enough memory is available; for GPU builds, verify CUDA/execution-provider compatibility.
4. Pin the CLIP/recognition models to ones bundled/known-good for your Immich version.

Example fix

# before — model cache may be corrupt
# (no action)

# after
docker exec immich-machine-learning rm -rf /cache/semanticsearch /cache/facial-recognition
# then restart the ML container and retry the job

# pre-flight: ensure cache dir is writable and model files exist
from pathlib import Path
if not Path(model.cache_dir).exists(): log.warning('cache missing, will download')

def can_load(model) -> bool:
    try:
        return Path(model.cache_dir).is_dir()
    except Exception:
        return False

try:
    await load(model)
except HTTPException as e:
    if e.status_code == 500 and 'Failed to load model' in (e.detail or ''):
        clear_and_reload(model)
    raise

When it happens

Trigger: A model's weights/session cannot be created — missing/corrupt model files, incompatible ONNX runtime, out-of-memory, unsupported model format — and the ONNX fallback also fails.

Common situations: Model files not fully downloaded or cache corrupted; ONNX runtime version mismatch with the model; insufficient RAM/VRAM; ARM/CPU without the right execution provider; mismatched Immich ML and model versions.

Related errors

• Invalid request format.
• Either image or text must be provided
• Attempted to clear cache, but rmtree is not safe on this pla
• Model file not found: {model_path}
• Invalid CLIP dimension size: ${dimSize}

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