{"record":{"id":"ea2e0fcb72b2bc6f","repo":"unslothai/unsloth","slug":"a-gguf-single-file-load-needs-the-checkpoint-filen","errorCode":null,"errorMessage":"A gguf/single_file load needs the checkpoint filename.","messagePattern":"A gguf/single_file load needs the checkpoint filename\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":1198,"sourceCode":"                        \"version. Reinstall Studio dependencies and retry.\"\n                    )\n        if kind != \"gguf\" and not _is_trusted_video_repo(repo_id):\n            raise ValueError(\n                f\"Non-GGUF video loads are limited to unsloth/* repos, the official \"\n                f\"family base repos, and local paths; '{repo_id}' is neither.\"\n            )\n        # Companions load with from_pretrained, so a base repo is held to the non-GGUF bar: a GGUF pick must not smuggle in a remote base.\n        if base_repo and (base_repo or \"\").strip() and not _is_trusted_video_repo(base_repo):\n            raise ValueError(\n                f\"base_repo is limited to unsloth/* repos, the official family base \"\n                f\"repos, and local paths; '{base_repo}' is neither.\"\n            )\n        # A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before the load.\n        from core.inference.diffusion import _assert_local_base_is_pipeline\n\n        _assert_local_base_is_pipeline(base_repo)\n        if kind in (\"gguf\", \"single_file\") and not gguf_filename:\n            raise ValueError(\"A gguf/single_file load needs the checkpoint filename.\")\n        if kind in (\"gguf\", \"single_file\") and fam.is_moe:\n            # A single checkpoint carries one expert; the other would load dense bf16, off-plan.\n            raise ValueError(\n                f\"'{fam.name}' is a dual-expert model: a single {kind} file covers only \"\n                f\"one of its two transformers. Load the diffusers pipeline repo \"\n                f\"('{fam.base_repo}') instead.\"\n            )\n        # A missing local checkpoint must fail HERE, before the route evicts a resident model.\n        if kind in (\"gguf\", \"single_file\"):\n            # Fail a kind/extension mismatch before the GPU handoff: gguf needs .gguf, single_file needs .safetensors.\n            is_gguf_name = (gguf_filename or \"\").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            if kind == \"single_file\" and not (gguf_filename or \"\").lower().endswith(\".safetensors\"):\n                raise ValueError(\n                    f\"'{gguf_filename}' is not a loadable single-file checkpoint \"","sourceCodeStart":1180,"sourceCodeEnd":1216,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L1180-L1216","documentation":"Raised when model_kind is 'gguf' or 'single_file' but gguf_filename (the checkpoint filename inside the repo/directory) is empty. Single-file loads need to know exactly which file to fetch, unlike pipeline loads that read model_index.json.","triggerScenarios":"Calling load with model_kind='gguf' or 'single_file' and gguf_filename=None/''/whitespace — most often because the field was named differently, dropped by a form, or the caller assumed repo_id alone is enough (which is only true when repo_id is a local FILE).","commonSituations":"Frontend sends model_kind but not the picked filename after a refactor; API client sets 'filename' instead of 'gguf_filename'; copy-pasted snippet from a pipeline load reused for a GGUF load; None defaults slipping through from a config parser.","solutions":["Pass gguf_filename with the checkpoint's file name, e.g. 'Wan2.5-Q4_K_M.gguf'.","Check the API schema: the field is gguf_filename, not filename/checkpoint.","If the target is a single local file, pass its full path as repo_id instead (kind checks then validate the suffix)."],"exampleFix":"# before\nload(repo_id='unsloth/wan25-gguf', model_kind='gguf', gguf_filename=None)\n\n# after\nload(repo_id='unsloth/wan25-gguf', model_kind='gguf',\n     gguf_filename='Wan2.5-I2V-Q4_K_M.gguf')","handlingStrategy":"validation","validationCode":"if model_kind in ('gguf', 'single_file') and not (gguf_filename or '').strip():\n    raise ValueError('pick a checkpoint filename before loading')  # fail in the client, not the backend","typeGuard":"def single_file_request_complete(kind: str, gguf_filename: str | None) -> bool:\n    return kind not in ('gguf', 'single_file') or bool((gguf_filename or '').strip())","tryCatchPattern":null,"preventionTips":["Make gguf_filename required in client schemas when kind is gguf/single_file.","Disable the Load action in the UI until a checkpoint file is picked for those kinds."],"tags":["video","gguf","validation","api-usage","missing-argument"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}