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

Kind/extension consistency check: model_kind resolved to 'gguf' but the supplied gguf_filename does not end in .gguf (case-insensitive). A 'gguf' load routes to GGUF loaders (sd.cpp or diffusers GGUF quantization) which require the GGUF container, so the mismatch is rejected before the GPU handoff.

Source

Thrown at studio/backend/core/inference/diffusion.py:1680

        if base_repo and base_repo.strip() and not _is_trusted_diffusion_repo(base_repo):
            raise ValueError(
                f"base_repo is restricted to unsloth/* repos (or a local path); got '{base_repo}'."
            )
        # A local base_repo loads as a full pipeline; reject a non-pipeline one before eviction.
        _assert_local_base_is_pipeline(base_repo)
        # Reject a bad LOCAL pick before the route evicts chat: a path-shaped repo_id must be on disk.
        local_root = Path(repo_id).expanduser()
        # Path-shaped: "."/".." prefix, a backslash (never in "org/name"), or an absolute path.
        path_shaped = (
            repo_id.startswith(("/", "\\", "~", ".")) or "\\" in repo_id or local_root.is_absolute()
        )
        if kind in ("gguf", "single_file"):
            if not gguf_filename:
                raise ValueError(f"a single-file checkpoint name is required for a '{kind}' load.")
            # Fail a kind/extension mismatch before the handoff: gguf needs .gguf, single_file must not.
            is_gguf_name = gguf_filename.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'.")
            # A single-file load must name a real .safetensors, else it evicts chat then fails in background.
            if kind == "single_file" and not gguf_filename.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)."
                )
            if local_root.exists():
                resolve_local_gguf_child(local_root, gguf_filename)
            elif path_shaped:
                raise FileNotFoundError(f"Local model path does not exist: {repo_id}")
        else:  # pipeline
            if gguf_filename:
                raise ValueError(
                    "a 'pipeline' load takes a full diffusers repo, not a single-file name."
                )
            if local_root.exists():

View on GitHub (pinned to 203007d190)

Solutions

1. If the file is truly GGUF, fix the filename/extension to end in .gguf.
2. If the file is .safetensors, change model_kind to 'single_file'.
3. If you meant the whole pipeline, remove the filename and use kind 'pipeline'.

Example fix

# before
manager.validate_load_request(repo_id="org/model", model_kind="gguf",
                               gguf_filename="flux_s1.safetensors")

# after: match the kind to the real file format
manager.validate_load_request(repo_id="org/model", model_kind="single_file",
                               gguf_filename="flux_s1.safetensors")

def kind_matches_filename(model_kind: str, gguf_filename: str | None) -> bool:
    if not gguf_filename:
        return True
    is_gguf = gguf_filename.lower().endswith(".gguf")
    return (model_kind == "gguf") == is_gguf

try:
    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)
except ValueError as e:
    if "requires a .gguf checkpoint name" in str(e):
        retry_with_kind_inferred_from_extension(r, f)
    else:
        raise

When it happens

Trigger: model_kind='gguf' with a filename like 'model.safetensors', 'model.ckpt', or a typo'd extension; also when a UI defaults kind to gguf while the user picked a safetensors file.

Common situations: Copy-pasting a .safetensors filename into a GGUF load form; preset saves kind separately from the file so they drift apart; extension typo like '.gguff'.

Related errors

• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• '{repo_id}' is a single-file GGUF repo; load it with model_k
• '{fam.name}' checkpoints are whole-pipeline single files and
• a single-file checkpoint name is required for a '{kind}' loa
• Local model path does not exist: {repo_id}

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