mudler/LocalAI · error · ValueError

model snapshot does not exist: {model_ref}

Error message

model snapshot does not exist: {model_ref}

What it means

Thrown by require_snapshot_file in the shared python backend model_utils when the model reference is neither a file ending with the expected suffix nor an existing directory. It means the resolved model reference (from request.ModelFile or request.Model) points to something that does not exist on disk.

Source

Thrown at backend/python/common/model_utils.py:16

import os


def resolve_model_reference(request, default=""):
    model_file = (getattr(request, "ModelFile", "") or "").strip()
    if model_file and os.path.exists(model_file):
        return model_file, True
    model = (getattr(request, "Model", "") or "").strip()
    return model or default, False


def require_snapshot_file(model_ref, suffix):
    if os.path.isfile(model_ref) and model_ref.endswith(suffix):
        return model_ref
    if not os.path.isdir(model_ref):
        raise ValueError(f"model snapshot does not exist: {model_ref}")

    matches = []
    for root, directories, files in os.walk(model_ref):
        directories.sort()
        for name in sorted(files):
            if name.endswith(suffix):
                matches.append(os.path.join(root, name))
    if len(matches) != 1:
        raise ValueError(
            f"model snapshot must contain exactly one {suffix} file; found {len(matches)}"
        )
    return matches[0]

View on GitHub (pinned to 44413a9d06)

Solutions

1. Install/pull the model first (e.g. via `local-ai models install <name>` or the gallery) so a snapshot directory exists under the configured models path.
2. Pass an absolute path to an existing snapshot directory or a direct file path ending with the expected suffix in request.ModelFile.
3. Verify the LocalAI models base path configuration matches where snapshots are actually stored.
4. Check for typos/case-sensitivity in the model reference string.

import os
ref, _ = resolve_model_reference(request, default="")
if not (os.path.isfile(ref) or os.path.isdir(ref)):
    raise FileNotFoundError(f"model not installed: {ref} — run local-ai models install")

def model_ref_exists(ref: str) -> bool:
    return os.path.isfile(ref) or os.path.isdir(ref)

try:
    snap = require_snapshot_file(model_ref, suffix)
except ValueError as e:
    logger.error("model resolution failed: %s", e)
    return error_reply(f"model missing: {model_ref}")

When it happens

Trigger: resolve_model_reference returned a request.Model value (no usable ModelFile) and that string is not an existing directory and not a matching file — e.g. a bare model name like 'ace-step-v1' with no local snapshot downloaded, or a typo'd path.

Common situations: Model gallery entry references a model that was never pulled to the models directory, the LocalAI models path is misconfigured so the backend looks in the wrong place, or the request passes a HuggingFace repo id where a local snapshot path is required.

Related errors

• model snapshot must contain exactly one {suffix} file; found
• no insightface pack '{self.model_pack}' found — install via
• onnx_direct engine requires both detector_onnx and recognize
• base_model must point to a LongCat-Video checkpoint
• ONNX model not found: {onnx_path}

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/412f50ff9a73ff1c. Report an issue: GitHub.