{"record":{"id":"ac0fdbaa37b6e35e","repo":"unslothai/unsloth","slug":"a-gguf-load-requires-a-gguf-checkpoint-name","errorCode":null,"errorMessage":"a 'gguf' load requires a .gguf checkpoint name.","messagePattern":"a 'gguf' load requires a \\.gguf checkpoint name\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1680,"sourceCode":"        if base_repo and base_repo.strip() and not _is_trusted_diffusion_repo(base_repo):\n            raise ValueError(\n                f\"base_repo is restricted to unsloth/* repos (or a local path); got '{base_repo}'.\"\n            )\n        # A local base_repo loads as a full pipeline; reject a non-pipeline one before eviction.\n        _assert_local_base_is_pipeline(base_repo)\n        # Reject a bad LOCAL pick before the route evicts chat: a path-shaped repo_id must be on disk.\n        local_root = Path(repo_id).expanduser()\n        # Path-shaped: \".\"/\"..\" prefix, a backslash (never in \"org/name\"), or an absolute path.\n        path_shaped = (\n            repo_id.startswith((\"/\", \"\\\\\", \"~\", \".\")) or \"\\\\\" in repo_id or local_root.is_absolute()\n        )\n        if kind in (\"gguf\", \"single_file\"):\n            if not gguf_filename:\n                raise ValueError(f\"a single-file checkpoint name is required for a '{kind}' load.\")\n            # Fail a kind/extension mismatch before the handoff: gguf needs .gguf, single_file must not.\n            is_gguf_name = gguf_filename.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            # A single-file load must name a real .safetensors, else it evicts chat then fails in background.\n            if kind == \"single_file\" and not gguf_filename.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            if local_root.exists():\n                resolve_local_gguf_child(local_root, gguf_filename)\n            elif path_shaped:\n                raise FileNotFoundError(f\"Local model path does not exist: {repo_id}\")\n        else:  # pipeline\n            if gguf_filename:\n                raise ValueError(\n                    \"a 'pipeline' load takes a full diffusers repo, not a single-file name.\"\n                )\n            if local_root.exists():","sourceCodeStart":1662,"sourceCodeEnd":1698,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1662-L1698","documentation":"Kind/extension consistency check: model_kind resolved to 'gguf' but the supplied gguf_filename does not end in .gguf (case-insensitive). A 'gguf' load routes to GGUF loaders (sd.cpp or diffusers GGUF quantization) which require the GGUF container, so the mismatch is rejected before the GPU handoff.","triggerScenarios":"model_kind='gguf' with a filename like 'model.safetensors', 'model.ckpt', or a typo'd extension; also when a UI defaults kind to gguf while the user picked a safetensors file.","commonSituations":"Copy-pasting a .safetensors filename into a GGUF load form; preset saves kind separately from the file so they drift apart; extension typo like '.gguff'.","solutions":["If the file is truly GGUF, fix the filename/extension to end in .gguf.","If the file is .safetensors, change model_kind to 'single_file'.","If you meant the whole pipeline, remove the filename and use kind 'pipeline'."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"gguf\",\n                               gguf_filename=\"flux_s1.safetensors\")\n\n# after: match the kind to the real file format\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"single_file\",\n                               gguf_filename=\"flux_s1.safetensors\")","handlingStrategy":"validation","validationCode":"def kind_matches_filename(model_kind: str, gguf_filename: str | None) -> bool:\n    if not gguf_filename:\n        return True\n    is_gguf = gguf_filename.lower().endswith(\".gguf\")\n    return (model_kind == \"gguf\") == is_gguf","typeGuard":null,"tryCatchPattern":"try:\n    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)\nexcept ValueError as e:\n    if \"requires a .gguf checkpoint name\" in str(e):\n        retry_with_kind_inferred_from_extension(r, f)\n    else:\n        raise","preventionTips":["Derive model_kind from the picked file's extension instead of storing it as an independent setting.","File pickers should filter to .gguf in gguf mode and .safetensors in single-file mode.","Unit-test the request builder so kind and filename can never disagree."],"tags":["validation","gguf","file-extension","load-kinds","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}