unslothai/unsloth · error · ValueError

A gguf/single_file load needs the checkpoint filename.

Error message

A gguf/single_file load needs the checkpoint filename.

What it means

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.

Source

Thrown at studio/backend/core/inference/video.py:1198

                        "version. Reinstall Studio dependencies and retry."
                    )
        if kind != "gguf" and not _is_trusted_video_repo(repo_id):
            raise ValueError(
                f"Non-GGUF video loads are limited to unsloth/* repos, the official "
                f"family base repos, and local paths; '{repo_id}' is neither."
            )
        # 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.
        if base_repo and (base_repo or "").strip() and not _is_trusted_video_repo(base_repo):
            raise ValueError(
                f"base_repo is limited to unsloth/* repos, the official family base "
                f"repos, and local paths; '{base_repo}' is neither."
            )
        # A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before the load.
        from core.inference.diffusion import _assert_local_base_is_pipeline

        _assert_local_base_is_pipeline(base_repo)
        if kind in ("gguf", "single_file") and not gguf_filename:
            raise ValueError("A gguf/single_file load needs the checkpoint filename.")
        if kind in ("gguf", "single_file") and fam.is_moe:
            # A single checkpoint carries one expert; the other would load dense bf16, off-plan.
            raise ValueError(
                f"'{fam.name}' is a dual-expert model: a single {kind} file covers only "
                f"one of its two transformers. Load the diffusers pipeline repo "
                f"('{fam.base_repo}') instead."
            )
        # A missing local checkpoint must fail HERE, before the route evicts a resident model.
        if kind in ("gguf", "single_file"):
            # Fail a kind/extension mismatch before the GPU handoff: gguf needs .gguf, single_file needs .safetensors.
            is_gguf_name = (gguf_filename or "").lower().endswith(".gguf")
            if kind == "gguf" and not is_gguf_name:
                raise ValueError("a 'gguf' load requires a .gguf checkpoint name.")
            if kind == "single_file" and is_gguf_name:
                raise ValueError("a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.")
            if kind == "single_file" and not (gguf_filename or "").lower().endswith(".safetensors"):
                raise ValueError(
                    f"'{gguf_filename}' is not a loadable single-file checkpoint "

View on GitHub (pinned to 203007d190)

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).

Example fix

# before
load(repo_id='unsloth/wan25-gguf', model_kind='gguf', gguf_filename=None)

# after
load(repo_id='unsloth/wan25-gguf', model_kind='gguf',
     gguf_filename='Wan2.5-I2V-Q4_K_M.gguf')

Defensive patterns

Strategy: validation

Validate before calling

if model_kind in ('gguf', 'single_file') and not (gguf_filename or '').strip():
    raise ValueError('pick a checkpoint filename before loading')  # fail in the client, not the backend

Type guard

def single_file_request_complete(kind: str, gguf_filename: str | None) -> bool:
    return kind not in ('gguf', 'single_file') or bool((gguf_filename or '').strip())

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/ea2e0fcb72b2bc6f. Report an issue: GitHub.