{"record":{"id":"f294441aaf928f8a","repo":"unslothai/unsloth","slug":"repo-id-is-a-single-file-gguf-repo-load-it-wi","errorCode":null,"errorMessage":"'{repo_id}' is a single-file GGUF repo; load it with model_kind 'gguf' and a .gguf filename, not as a full pipeline.","messagePattern":"'(.+?)' is a single-file GGUF repo; load it with model_kind 'gguf' and a \\.gguf filename, not as a full pipeline\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1707,"sourceCode":"            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(\n                        f\"Local pipeline directory has no model_index.json: {repo_id}\"\n                    )\n            elif path_shaped:\n                raise FileNotFoundError(f\"Local model path does not exist: {repo_id}\")\n            elif repo_id.upper().endswith(\"-GGUF\"):\n                # A remote \"*-GGUF\" id is not a pipeline; reject here instead of evicting chat then failing.\n                raise ValueError(\n                    f\"'{repo_id}' is a single-file GGUF repo; load it with model_kind 'gguf' \"\n                    f\"and a .gguf filename, not as a full pipeline.\"\n                )\n        return fam\n\n    def preflight_base_access(\n        self,\n        repo_id: str,\n        fam: Optional[DiffusionFamily],\n        *,\n        gguf_filename: Optional[str] = None,\n        model_kind: Optional[str] = None,\n        base_repo: Optional[str] = None,\n        hf_token: Optional[str] = None,\n    ) -> None:\n        \"\"\"The gated/unreadable-base and FLUX.2 size-pairing refusals, run by the route BEFORE it\n        takes the GPU.\n","sourceCodeStart":1689,"sourceCodeEnd":1725,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1689-L1725","documentation":"Heuristic rejection of a common misload: the repo id ends in '-GGUF' (case-insensitive), which marks Hugging Face single-file GGUF repos, but the request is a pipeline load (no gguf_filename, non-path id). Such repos contain quantized .gguf files rather than a diffusers layout, so a pipeline from_pretrained would fail after eviction; the validation refuses it up front with the correct invocation spelled out.","triggerScenarios":"Passing an id like 'org/Model-GGUF' or 'city96/FLUX.1-dev-gguf' as a pipeline load (no model_kind, no gguf_filename) - typically copy-pasting a GGUF repo link straight from Hugging Face into a pipeline field.","commonSituations":"User browses HF, finds the -GGUF republish ranked first in search, and pastes it where a pipeline repo belongs; UI search surfaces GGUF repos without indicating they need the GGUF load mode.","solutions":["Load the GGUF repo the intended way: model_kind='gguf' plus a .gguf filename from that repo (e.g. 'flux1-dev-Q4_K_S.gguf').","Or switch to the base pipeline repo (drop the -GGUF suffix / use the original org's repo or its unsloth mirror).","List the -GGUF repo's files to pick the quantization level you want as the checkpoint name."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"city96/FLUX.1-dev-gguf\")\n# ValueError: ... is a single-file GGUF repo; load it with model_kind 'gguf' ...\n\n# after\nmanager.validate_load_request(repo_id=\"city96/FLUX.1-dev-gguf\",\n    model_kind=\"gguf\", gguf_filename=\"flux1-dev-Q4_K_S.gguf\")","handlingStrategy":"validation","validationCode":"def looks_like_gguf_repo(repo_id: str) -> bool:\n    return repo_id.upper().endswith(\"-GGUF\")","typeGuard":null,"tryCatchPattern":"try:\n    fam = manager.validate_load_request(repo_id=r)\nexcept ValueError as e:\n    if \"single-file GGUF repo\" in str(e):\n        list_gguf_files_and_switch_mode(r)\n    else:\n        raise","preventionTips":["When a pasted id ends in -GGUF, switch the form to gguf mode and list the repo's .gguf files automatically.","Tag GGUF repos distinctly in model search results so users know they need the gguf load kind.","Keep the base pipeline repo as the default suggestion; offer -GGUF mirrors only in gguf mode."],"tags":["gguf","huggingface","pipeline","validation","load-kinds","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}