unslothai/unsloth · error · ValueError

a .gguf checkpoint needs model_kind 'gguf', not 'single_file

Error message

a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.

What it means

The inverse of [447]: the checkpoint filename ends in .gguf but model_kind was sent as 'single_file'. GGUF files must be loaded with model_kind='gguf'; the message names the correct kind explicitly.

Source

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

        _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
            elif root.is_file():
                # The loader hands a local FILE straight through (ignoring gguf_filename), so the file's own suffix must match the kind.

View on GitHub (pinned to 203007d190)

Solutions

1. Set model_kind='gguf' for .gguf files.
2. Or choose a .safetensors checkpoint if you truly need the single_file (ComfyUI-style) path.
3. Derive model_kind from the file extension in client code: kind = 'gguf' if name.endswith('.gguf') else 'single_file'.

Example fix

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

# after
load(repo_id='unsloth/x', model_kind='gguf', gguf_filename='x-Q4_K_M.gguf')

if gguf_filename.lower().endswith('.gguf'):
    model_kind = 'gguf'  # never send 'single_file' with a .gguf name

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

When it happens

Trigger: load(model_kind='single_file', gguf_filename='anything.gguf') — is_gguf_name is true while kind is 'single_file'.

Common situations: Defaults or presets written when only 'single_file' existed; mapping 'quantized file' to 'single_file' in an integration; UI defaulting the kind dropdown to single_file.

Related errors

• a single-file checkpoint name is required for a '{kind}' loa
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• '{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/1b761681ecc8ede8. Report an issue: GitHub.