{"record":{"id":"b865fa2932af9bbe","repo":"unslothai/unsloth","slug":"a-pipeline-load-takes-a-full-diffusers-repo-not","errorCode":null,"errorMessage":"a 'pipeline' load takes a full diffusers repo, not a single-file name.","messagePattern":"a 'pipeline' load takes a full diffusers repo, not a single-file name\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1695,"sourceCode":"            # 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(\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(","sourceCodeStart":1677,"sourceCodeEnd":1713,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1677-L1713","documentation":"A 'pipeline' load takes a full diffusers repo (or local pipeline directory), not an individual checkpoint file: this ValueError fires when the kind resolved to pipeline but a gguf_filename was still supplied. The two parameters are mutually exclusive by kind, and the cheap validation catches the contradiction before GPU eviction.","triggerScenarios":"model_kind='pipeline' (explicitly, or resolved from defaults) together with a non-empty gguf_filename - e.g. a UI that sends both fields because the user picked a file then switched the mode to pipeline.","commonSituations":"Client reuses one request struct for all load kinds and leaves stale fields populated; user changed mode after picking a file; preset merging concatenates options from different kinds.","solutions":["Drop gguf_filename for a pipeline load - the whole repo (or local directory with model_index.json) is the unit.","If you want that single file loaded, set model_kind to 'single_file' (for .safetensors) or 'gguf' (for .gguf).","Fix the client so kind and filename fields are cleared together when the mode changes."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"unsloth/FLUX.1-dev\",\n    model_kind=\"pipeline\", gguf_filename=\"t-Q4.gguf\")\n\n# after: pipeline takes the repo only\nmanager.validate_load_request(repo_id=\"unsloth/FLUX.1-dev\", model_kind=\"pipeline\")","handlingStrategy":"validation","validationCode":"kind = resolve_model_kind(gguf_filename, model_kind)\nif kind == \"pipeline\":\n    gguf_filename = None  # pipeline takes the repo, not a file","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 \"takes a full diffusers repo\" in str(e):\n        manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=None)\n    else:\n        raise","preventionTips":["Model kind and checkpoint filename are one coupled pair in the request - always set or clear them together.","In UIs, changing the load mode should clear the file field (and vice versa).","Reject requests where resolve_model_kind contradicts the presence of gguf_filename before they reach the backend."],"tags":["validation","pipeline","load-kinds","parameter-conflict","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}