{"record":{"id":"412f50ff9a73ff1c","repo":"mudler/LocalAI","slug":"model-snapshot-does-not-exist-model-ref","errorCode":null,"errorMessage":"model snapshot does not exist: {model_ref}","messagePattern":"model snapshot does not exist: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/common/model_utils.py","lineNumber":16,"sourceCode":"import os\n\n\ndef resolve_model_reference(request, default=\"\"):\n    model_file = (getattr(request, \"ModelFile\", \"\") or \"\").strip()\n    if model_file and os.path.exists(model_file):\n        return model_file, True\n    model = (getattr(request, \"Model\", \"\") or \"\").strip()\n    return model or default, False\n\n\ndef require_snapshot_file(model_ref, suffix):\n    if os.path.isfile(model_ref) and model_ref.endswith(suffix):\n        return model_ref\n    if not os.path.isdir(model_ref):\n        raise ValueError(f\"model snapshot does not exist: {model_ref}\")\n\n    matches = []\n    for root, directories, files in os.walk(model_ref):\n        directories.sort()\n        for name in sorted(files):\n            if name.endswith(suffix):\n                matches.append(os.path.join(root, name))\n    if len(matches) != 1:\n        raise ValueError(\n            f\"model snapshot must contain exactly one {suffix} file; found {len(matches)}\"\n        )\n    return matches[0]\n","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/common/model_utils.py#L1-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Pass an absolute path to an existing snapshot directory or a direct file path ending with the expected suffix in request.ModelFile.","Verify the LocalAI models base path configuration matches where snapshots are actually stored.","Check for typos/case-sensitivity in the model reference string."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import os\nref, _ = resolve_model_reference(request, default=\"\")\nif not (os.path.isfile(ref) or os.path.isdir(ref)):\n    raise FileNotFoundError(f\"model not installed: {ref} — run local-ai models install\")","typeGuard":"def model_ref_exists(ref: str) -> bool:\n    return os.path.isfile(ref) or os.path.isdir(ref)","tryCatchPattern":"try:\n    snap = require_snapshot_file(model_ref, suffix)\nexcept ValueError as e:\n    logger.error(\"model resolution failed: %s\", e)\n    return error_reply(f\"model missing: {model_ref}\")","preventionTips":["Pre-flight check that the model snapshot directory exists before starting the backend.","Automate model installation in deployment scripts so refs never dangle.","Pass absolute ModelFile paths when you control the request."],"tags":["model-loading","path-validation","localai","configuration"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}