{"record":{"id":"605268074483506e","repo":"unslothai/unsloth","slug":"a-gguf-checkpoint-needs-model-kind-gguf-not-s","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1682,"sourceCode":"                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():\n                if not (local_root / \"model_index.json\").exists():\n                    raise FileNotFoundError(","sourceCodeStart":1664,"sourceCodeEnd":1700,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1664-L1700","documentation":"The mirror of error 71: the filename ends in .gguf but model_kind is 'single_file'. The single-file path loads a .safetensors checkpoint via from_single_file, so a .gguf name means the caller actually wants the GGUF path and mislabelled the kind.","triggerScenarios":"model_kind='single_file' with gguf_filename ending in .gguf (case-insensitive) - typically a stale kind field or a UI that renamed its modes while the filename carried over.","commonSituations":"Older configs that called every transformer-only load 'single_file' before the gguf kind existed; UI mode renamed from single-file to include GGUF but the stored kind string was not migrated.","solutions":["Set model_kind='gguf' (or drop model_kind entirely - a .gguf filename usually resolves the kind automatically).","If you really want the single-file safetensors path, pick the corresponding .safetensors filename from the repo."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"single_file\",\n                               gguf_filename=\"model-Q4_K_M.gguf\")\n\n# after\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"gguf\",\n                               gguf_filename=\"model-Q4_K_M.gguf\")","handlingStrategy":"validation","validationCode":"if gguf_filename and gguf_filename.lower().endswith(\".gguf\"):\n    assert model_kind != \"single_file\", \"a .gguf name means kind '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 \"needs model_kind 'gguf'\" in str(e):\n        manager.validate_load_request(repo_id=r, model_kind=\"gguf\", gguf_filename=f)\n    else:\n        raise","preventionTips":["Migrate legacy configs that labelled every transformer-only load 'single_file' - GGUF files need the 'gguf' kind.","Treat the file extension as the source of truth and normalize the kind field from it on load of any saved preset."],"tags":["validation","gguf","single-file","load-kinds","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}