{"record":{"id":"f9bc8d70f9772de6","repo":"unslothai/unsloth","slug":"a-gguf-load-requires-a-gguf-checkpoint-name-f9bc8d","errorCode":null,"errorMessage":"a 'gguf' load requires a .gguf checkpoint name.","messagePattern":"a 'gguf' load requires a \\.gguf checkpoint name\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":1211,"sourceCode":"        # A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before the load.\n        from core.inference.diffusion import _assert_local_base_is_pipeline\n\n        _assert_local_base_is_pipeline(base_repo)\n        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","sourceCodeStart":1193,"sourceCodeEnd":1229,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L1193-L1229","documentation":"Raised when model_kind is 'gguf' but the provided checkpoint filename does not end in .gguf (case-insensitive). The kind and the file extension must agree — a .safetensors name under kind 'gguf' means the caller mislabeled the load, and failing here is cheaper than failing at the GPU handoff.","triggerScenarios":"load(model_kind='gguf', gguf_filename='model.safetensors') or any name not ending .gguf; commonly after switching model_kind in a form while the old filename persisted.","commonSituations":"UI toggles kind radio but keeps the previously picked file; scripts templating the filename with the wrong extension; renaming quantized files to drop the extension.","solutions":["Pick a .gguf checkpoint file for a 'gguf' load.","If the file really is .safetensors, use model_kind='single_file' instead.","Fix the client so the kind and the picked filename change together."],"exampleFix":"# before\nload(repo_id='unsloth/x', model_kind='gguf', gguf_filename='x-q4.safetensors')\n\n# after\nload(repo_id='unsloth/x', model_kind='single_file', gguf_filename='x-q4.safetensors')","handlingStrategy":"validation","validationCode":"if model_kind == 'gguf' and not gguf_filename.lower().endswith('.gguf'):\n    model_kind = 'single_file' if gguf_filename.lower().endswith('.safetensors') else None  # or surface an error","typeGuard":"def kind_matches_name(kind: str, name: str) -> bool:\n    n = (name or '').lower()\n    return not (kind == 'gguf' and not n.endswith('.gguf'))","tryCatchPattern":null,"preventionTips":["Derive model_kind from the picked file's extension in the client.","Keep the kind control and file picker coupled in UIs."],"tags":["video","gguf","validation","file-extension"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}