{"record":{"id":"c09606306dfb4f3d","repo":"unslothai/unsloth","slug":"a-single-file-checkpoint-name-is-required-for-a","errorCode":null,"errorMessage":"a single-file checkpoint name is required for a '{kind}' load.","messagePattern":"a single-file checkpoint name is required for a '(.+?)' load\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/diffusion.py","lineNumber":1676,"sourceCode":"                f\"Non-GGUF diffusion loads are restricted to unsloth/* repos (or a local \"\n                f\"path); got '{repo_id}'. Pass a gguf_filename to load a GGUF instead.\"\n            )\n        # The companion base repo also loads via from_pretrained, so it must clear the same trust bar.\n        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:","sourceCodeStart":1658,"sourceCodeEnd":1694,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion.py#L1658-L1694","documentation":"Raised in the cheap, network-free validation when the resolved load kind is 'gguf' or 'single_file' but no checkpoint filename was supplied. Both transformer-only paths need to know which file inside the repo (or local directory) to load; its absence fails here rather than after the resident GPU model has been evicted.","triggerScenarios":"Calling validate_load_request / load with model_kind='gguf' or 'single_file' (or a family/parameters combination that resolves to those kinds) with gguf_filename=None or empty.","commonSituations":"UI sends model_kind but drops the filename field; saved preset from a pipeline load has kind overwritten but no file picked; scripting the API and forgetting the second positional-style parameter.","solutions":["Pass the checkpoint filename: a .gguf name for a gguf load, a .safetensors name for a single_file load.","If you meant a full pipeline load, set model_kind='pipeline' (or leave unset and pass no gguf_filename).","List the repo's files (HF file tree or local dir) to get the exact filename including quant suffix."],"exampleFix":"# before\nmanager.validate_load_request(repo_id=\"org/model\", model_kind=\"gguf\")\n# ValueError: a single-file checkpoint name is required for a 'gguf' load.\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":"kind = resolve_model_kind(gguf_filename, model_kind)\nif kind in (\"gguf\", \"single_file\"):\n    assert gguf_filename, f\"a checkpoint name is required for a '{kind}' load\"","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 \"checkpoint name is required\" in str(e):\n        prompt_for_checkpoint_file(r, k)\n    else:\n        raise","preventionTips":["Make filename a required field in any UI that offers gguf/single_file modes.","Clear gguf_filename whenever the mode switches to pipeline so stale state cannot produce kind/param mismatches.","Prefer letting gguf_filename drive kind inference rather than setting both independently."],"tags":["validation","gguf","single-file","missing-parameter","diffusion"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}