unslothai/unsloth · error · ValueError

a 'gguf' load requires a .gguf checkpoint name.

Error message

a 'gguf' load requires a .gguf checkpoint name.

What it means

Raised when model_kind is 'gguf' but the provided checkpoint filename does not end in .gguf (case-insensitive). The kind and the file extension must agree — a .safetensors name under kind 'gguf' means the caller mislabeled the load, and failing here is cheaper than failing at the GPU handoff.

Source

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

        # 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 "
                    f"(expected a .safetensors name; use a .gguf name for a GGUF load)."
                )
            root = Path(repo_id).expanduser()
            # Path-shaped: "."/".." prefix, a backslash (never in "org/name"), or an absolute path, so a missing local pick fails before the handoff.
            path_shaped = (
                repo_id.startswith(("/", "\\", "~", ".")) or "\\" in repo_id or root.is_absolute()
            )
            if root.is_dir():
                from .diffusion_families import resolve_local_gguf_child
                try:
                    resolve_local_gguf_child(root, gguf_filename or "")
                except Exception as exc:  # noqa: BLE001 -- surface as client input error
                    raise ValueError(str(exc)) from exc

View on GitHub (pinned to 203007d190)

Solutions

1. Pick a .gguf checkpoint file for a 'gguf' load.
2. If the file really is .safetensors, use model_kind='single_file' instead.
3. Fix the client so the kind and the picked filename change together.

Example fix

# before
load(repo_id='unsloth/x', model_kind='gguf', gguf_filename='x-q4.safetensors')

# after
load(repo_id='unsloth/x', model_kind='single_file', gguf_filename='x-q4.safetensors')

if model_kind == 'gguf' and not gguf_filename.lower().endswith('.gguf'):
    model_kind = 'single_file' if gguf_filename.lower().endswith('.safetensors') else None  # or surface an error

def kind_matches_name(kind: str, name: str) -> bool:
    n = (name or '').lower()
    return not (kind == 'gguf' and not n.endswith('.gguf'))

When it happens

Trigger: load(model_kind='gguf', gguf_filename='model.safetensors') or any name not ending .gguf; commonly after switching model_kind in a form while the old filename persisted.

Common situations: UI toggles kind radio but keeps the previously picked file; scripts templating the filename with the wrong extension; renaming quantized files to drop the extension.

Related errors

• Local checkpoint '{repo_id}' is not a .gguf file; a 'gguf' l
• a 'gguf' load requires a .gguf checkpoint name.
• '{repo_id}' is a GGUF repo: pick one of its .gguf files (ggu
• '{Path(gguf_filename or '').name}' is the {picked} partition
• base_repo is limited to unsloth/* repos, the official family

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