{"record":{"id":"ba517ede08e2560c","repo":"unslothai/unsloth","slug":"gguf-filename-is-not-a-loadable-single-file-ch","errorCode":null,"errorMessage":"'{gguf_filename}' is not a loadable single-file checkpoint (expected a .safetensors name; use a .gguf name for a GGUF load).","messagePattern":"'(.+?)' is not a loadable single-file checkpoint \\(expected a \\.safetensors name; use a \\.gguf name for a GGUF load\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1685,"sourceCode":"        _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(\n                        f\"Local pipeline directory has no model_index.json: {repo_id}\"\n                    )\n            elif path_shaped:","sourceCodeStart":1667,"sourceCodeEnd":1703,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1667-L1703","documentation":"A single_file load must name a real .safetensors checkpoint: from_single_file deserializes a safetensors pipeline file. This fires when kind='single_file', the name is not .gguf (that is error 72), but it is also not .safetensors - e.g. a .ckpt, a bare name, or a diffusion pb/safetensors variant the loader cannot consume. Caught pre-eviction because otherwise chat would be evicted and the load fail in the background.","triggerScenarios":"model_kind='single_file' with gguf_filename like 'flux.ckpt', 'model', or 'v1.sft' - anything that is neither .gguf nor .safetensors.","commonSituations":"Legacy SD1.5-era .ckpt files assumed loadable; filename pasted without its extension; UI file list showing config/json files that the user selects as the checkpoint.","solutions":["Pick the .safetensors single-file checkpoint from the repo - modern single-file releases ship .safetensors.","If only a .ckpt exists, convert it to .safetensors first (diffusers provides converters), or find a republish.","For a .gguf file, use model_kind='gguf' instead."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"single_file\",\n                               gguf_filename=\"sd15.ckpt\")\n# ValueError: 'sd15.ckpt' is not a loadable single-file checkpoint ...\n\n# after\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"single_file\",\n                               gguf_filename=\"sd15.safetensors\")","handlingStrategy":"validation","validationCode":"def loadable_single_file(name: str | None) -> bool:\n    return bool(name) and name.lower().endswith(\".safetensors\")","typeGuard":null,"tryCatchPattern":"try:\n    fam = manager.validate_load_request(repo_id=r, model_kind=\"single_file\", gguf_filename=f)\nexcept ValueError as e:\n    if \"not a loadable single-file checkpoint\" in str(e):\n        prompt_for_safetensors_file(r)\n    else:\n        raise","preventionTips":["Restrict single-file pickers to .safetensors entries; grey out .ckpt/.sft/config files.","Convert legacy .ckpt archives to .safetensors once, offline, rather than retrying them per load.","Show the repo's file list (filtered) instead of a free-text filename field."],"tags":["validation","safetensors","single-file","file-format","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}