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

Raised when model_kind='single_file' and the checkpoint filename is neither .safetensors nor .gguf — e.g. .ckpt, .pt, or no extension. The single_file path only loads .safetensors; the message says so and reminds that .gguf names belong to a 'gguf' load.

Source

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

        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.
                suffix = root.suffix.lower()
                if kind == "gguf" and suffix != ".gguf":

View on GitHub (pinned to 203007d190)

Solutions

1. Convert the checkpoint to .safetensors and pass that filename.
2. Pick an existing .safetensors file from the repo/directory.
3. If the file is actually GGUF, switch model_kind to 'gguf'.

Example fix

# before
load(repo_id='unsloth/x', model_kind='single_file', gguf_filename='wan25.ckpt')

# after (convert once, then)
load(repo_id='unsloth/x', model_kind='single_file', gguf_filename='wan25.safetensors')

n = (gguf_filename or '').lower()
if model_kind == 'single_file' and not n.endswith('.safetensors'):
    raise ValueError('single_file needs a .safetensors checkpoint')  # client-side

def single_file_name_ok(name: str) -> bool:
    return (name or '').lower().endswith('.safetensors')

When it happens

Trigger: load(model_kind='single_file', gguf_filename='model.ckpt') or 'model.pt' / 'model.bin' / extensionless names.

Common situations: Old Stable Diffusion .ckpt habits carried into a video workflow; mixed model folders where TorchScript/pickle files sit next to safetensors; filename typos.

Related errors

• '{gguf_filename}' is not a loadable single-file checkpoint (
• Local checkpoint '{repo_id}' is not a .safetensors file; a '
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• a single-file checkpoint name is required for a '{kind}' loa
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file

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