unslothai/unsloth · error · ValueError

'{gguf_filename}' is not a loadable single-file checkpoint (

Error message

'{gguf_filename}' is not a loadable single-file checkpoint (expected a .safetensors name; use a .gguf name for a GGUF load).

What it means

A single_file load must name a real .safetensors checkpoint: from_single_file deserializes a safetensors pipeline file. This fires when kind='single_file', the name is not .gguf (that is error 72), but it is also not .safetensors - e.g. a .ckpt, a bare name, or a diffusion pb/safetensors variant the loader cannot consume. Caught pre-eviction because otherwise chat would be evicted and the load fail in the background.

Source

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

        _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():
                if not (local_root / "model_index.json").exists():
                    raise FileNotFoundError(
                        f"Local pipeline directory has no model_index.json: {repo_id}"
                    )
            elif path_shaped:

View on GitHub (pinned to 203007d190)

Solutions

Pick the .safetensors single-file checkpoint from the repo - modern single-file releases ship .safetensors.
If only a .ckpt exists, convert it to .safetensors first (diffusers provides converters), or find a republish.
For a .gguf file, use model_kind='gguf' instead.

Example fix

# before
manager.validate_load_request(repo_id="org/model", model_kind="single_file",
                               gguf_filename="sd15.ckpt")
# ValueError: 'sd15.ckpt' is not a loadable single-file checkpoint ...

# after
manager.validate_load_request(repo_id="org/model", model_kind="single_file",
                               gguf_filename="sd15.safetensors")

Defensive patterns

Strategy: validation

Validate before calling

def loadable_single_file(name: str | None) -> bool:
    return bool(name) and name.lower().endswith(".safetensors")

Try / catch

try:
    fam = manager.validate_load_request(repo_id=r, model_kind="single_file", gguf_filename=f)
except ValueError as e:
    if "not a loadable single-file checkpoint" in str(e):
        prompt_for_safetensors_file(r)
    else:
        raise

Prevention

Restrict single-file pickers to .safetensors entries; grey out .ckpt/.sft/config files.
Convert legacy .ckpt archives to .safetensors once, offline, rather than retrying them per load.
Show the repo's file list (filtered) instead of a free-text filename field.

When it happens

Trigger: model_kind='single_file' with gguf_filename like 'flux.ckpt', 'model', or 'v1.sft' - anything that is neither .gguf nor .safetensors.

Common situations: Legacy SD1.5-era .ckpt files assumed loadable; filename pasted without its extension; UI file list showing config/json files that the user selects as the checkpoint.

Related errors

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