{"record":{"id":"1b761681ecc8ede8","repo":"unslothai/unsloth","slug":"a-gguf-checkpoint-needs-model-kind-gguf-not-s-1b7616","errorCode":null,"errorMessage":"a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.","messagePattern":"a \\.gguf checkpoint needs model_kind 'gguf', not 'single_file'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":1213,"sourceCode":"\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\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.","sourceCodeStart":1195,"sourceCodeEnd":1231,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L1195-L1231","documentation":"The inverse of [447]: the checkpoint filename ends in .gguf but model_kind was sent as 'single_file'. GGUF files must be loaded with model_kind='gguf'; the message names the correct kind explicitly.","triggerScenarios":"load(model_kind='single_file', gguf_filename='anything.gguf') — is_gguf_name is true while kind is 'single_file'.","commonSituations":"Defaults or presets written when only 'single_file' existed; mapping 'quantized file' to 'single_file' in an integration; UI defaulting the kind dropdown to single_file.","solutions":["Set model_kind='gguf' for .gguf files.","Or choose a .safetensors checkpoint if you truly need the single_file (ComfyUI-style) path.","Derive model_kind from the file extension in client code: kind = 'gguf' if name.endswith('.gguf') else 'single_file'."],"exampleFix":"# before\nload(repo_id='unsloth/x', model_kind='single_file', gguf_filename='x-Q4_K_M.gguf')\n\n# after\nload(repo_id='unsloth/x', model_kind='gguf', gguf_filename='x-Q4_K_M.gguf')","handlingStrategy":"validation","validationCode":"if gguf_filename.lower().endswith('.gguf'):\n    model_kind = 'gguf'  # never send 'single_file' with a .gguf name","typeGuard":"def not_gguf_under_single_file(kind: str, name: str) -> bool:\n    return not (kind == 'single_file' and (name or '').lower().endswith('.gguf'))","tryCatchPattern":null,"preventionTips":["Auto-map .gguf -> model_kind 'gguf' in request builders.","Audit presets written before the gguf/single_file split was introduced."],"tags":["video","gguf","single-file","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}