{"record":{"id":"524063a9322e8b31","repo":"unslothai/unsloth","slug":"gguf-filename-is-not-a-loadable-single-file-ch-524063","errorCode":null,"errorMessage":"'{gguf_filename}' is not a loadable single-file checkpoint (expected a .safetensors name; use a .gguf name for a GGUF load).","messagePattern":"'(.+?)' is not a loadable single-file checkpoint \\(expected a \\.safetensors name; use a \\.gguf name for a GGUF load\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":1215,"sourceCode":"        if kind in (\"gguf\", \"single_file\") and not gguf_filename:\n            raise ValueError(\"A gguf/single_file load needs the checkpoint filename.\")\n        if kind in (\"gguf\", \"single_file\") and fam.is_moe:\n            # A single checkpoint carries one expert; the other would load dense bf16, off-plan.\n            raise ValueError(\n                f\"'{fam.name}' is a dual-expert model: a single {kind} file covers only \"\n                f\"one of its two transformers. Load the diffusers pipeline repo \"\n                f\"('{fam.base_repo}') instead.\"\n            )\n        # A missing local checkpoint must fail HERE, before the route evicts a resident model.\n        if kind in (\"gguf\", \"single_file\"):\n            # Fail a kind/extension mismatch before the GPU handoff: gguf needs .gguf, single_file needs .safetensors.\n            is_gguf_name = (gguf_filename or \"\").lower().endswith(\".gguf\")\n            if kind == \"gguf\" and not is_gguf_name:\n                raise ValueError(\"a 'gguf' load requires a .gguf checkpoint name.\")\n            if kind == \"single_file\" and is_gguf_name:\n                raise ValueError(\"a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.\")\n            if kind == \"single_file\" and not (gguf_filename or \"\").lower().endswith(\".safetensors\"):\n                raise ValueError(\n                    f\"'{gguf_filename}' is not a loadable single-file checkpoint \"\n                    f\"(expected a .safetensors name; use a .gguf name for a GGUF load).\"\n                )\n            root = Path(repo_id).expanduser()\n            # Path-shaped: \".\"/\"..\" prefix, a backslash (never in \"org/name\"), or an absolute path, so a missing local pick fails before the handoff.\n            path_shaped = (\n                repo_id.startswith((\"/\", \"\\\\\", \"~\", \".\")) or \"\\\\\" in repo_id or root.is_absolute()\n            )\n            if root.is_dir():\n                from .diffusion_families import resolve_local_gguf_child\n                try:\n                    resolve_local_gguf_child(root, gguf_filename or \"\")\n                except Exception as exc:  # noqa: BLE001 -- surface as client input error\n                    raise ValueError(str(exc)) from exc\n            elif root.is_file():\n                # The loader hands a local FILE straight through (ignoring gguf_filename), so the file's own suffix must match the kind.\n                suffix = root.suffix.lower()\n                if kind == \"gguf\" and suffix != \".gguf\":","sourceCodeStart":1197,"sourceCodeEnd":1233,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L1197-L1233","documentation":"Raised when model_kind='single_file' and the checkpoint filename is neither .safetensors nor .gguf — e.g. .ckpt, .pt, or no extension. The single_file path only loads .safetensors; the message says so and reminds that .gguf names belong to a 'gguf' load.","triggerScenarios":"load(model_kind='single_file', gguf_filename='model.ckpt') or 'model.pt' / 'model.bin' / extensionless names.","commonSituations":"Old Stable Diffusion .ckpt habits carried into a video workflow; mixed model folders where TorchScript/pickle files sit next to safetensors; filename typos.","solutions":["Convert the checkpoint to .safetensors and pass that filename.","Pick an existing .safetensors file from the repo/directory.","If the file is actually GGUF, switch model_kind to 'gguf'."],"exampleFix":"# before\nload(repo_id='unsloth/x', model_kind='single_file', gguf_filename='wan25.ckpt')\n\n# after (convert once, then)\nload(repo_id='unsloth/x', model_kind='single_file', gguf_filename='wan25.safetensors')","handlingStrategy":"validation","validationCode":"n = (gguf_filename or '').lower()\nif model_kind == 'single_file' and not n.endswith('.safetensors'):\n    raise ValueError('single_file needs a .safetensors checkpoint')  # client-side","typeGuard":"def single_file_name_ok(name: str) -> bool:\n    return (name or '').lower().endswith('.safetensors')","tryCatchPattern":null,"preventionTips":["Filter the file picker to .safetensors when single_file is selected.","Convert legacy .ckpt/.pt archives to .safetensors at import time."],"tags":["video","safetensors","single-file","validation","file-format"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}