mudler/LocalAI · error · ValueError

model snapshot must contain exactly one {suffix} file; found

Error message

model snapshot must contain exactly one {suffix} file; found {len(matches)}

What it means

Thrown by require_snapshot_file after walking the snapshot directory when the count of files ending with the expected suffix is not exactly one. The loader requires an unambiguous artifact: zero matches means the snapshot is incomplete, two or more means it cannot choose safely.

Source

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

        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. List files under the snapshot directory (find <dir> -name '*<suffix>') to see whether the problem is zero or multiple matches.
2. If multiple: keep exactly one intended file and delete/move the others, or point request.ModelFile directly at the file you want (the direct-file branch bypasses the walk).
3. If zero: re-download/reinstall the model snapshot; the download was likely truncated or the layout changed upstream.
4. For pack layouts with legitimately several variants, split them into per-variant snapshot directories.

import os
matches = [os.path.join(r, f) for r, d, fs in os.walk(model_ref) for f in fs if f.endswith(suffix)]
assert len(matches) == 1, f"expected exactly 1 {suffix} file, found {len(matches)}: {matches}"

try:
    model_file = require_snapshot_file(model_ref, ".safetensors")
except ValueError as e:
    if "exactly one" in str(e):
        # ambiguous snapshot: surface choices to user instead of failing silently
        raise
    raise

When it happens

Trigger: os.walk over the model_ref directory finds 0 files with the suffix (incomplete download, wrong snapshot layout) or finds 2+ (multiple variants dumped in one directory, e.g. both a quantized and full model file).

Common situations: An interrupted model download that left a partial snapshot, a user manually copying several model variants into one folder, or a gallery pack that ships more than one file of the same type (e.g. two .onnx or two .safetensors).

Related errors

• model snapshot does not exist: {model_ref}
• 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/1d967396c316b7a5. Report an issue: GitHub.