unslothai/unsloth · error · ValueError

Local checkpoint '{repo_id}' is not a .gguf file; a 'gguf' l

Error message

Local checkpoint '{repo_id}' is not a .gguf file; a 'gguf' load needs a .gguf checkpoint.

What it means

Raised when repo_id is a local FILE (not a directory) passed to a 'gguf' load whose suffix is not .gguf. The loader hands a local file straight through, ignoring gguf_filename, so the file's own extension must match the declared kind; the mismatch is caught before the GPU handoff.

Source

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

                    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":
                    raise ValueError(
                        f"Local checkpoint '{repo_id}' is not a .gguf file; a 'gguf' load "
                        f"needs a .gguf checkpoint."
                    )
                if kind == "single_file" and suffix != ".safetensors":
                    raise ValueError(
                        f"Local checkpoint '{repo_id}' is not a .safetensors file; a "
                        f"'single_file' load needs a .safetensors checkpoint."
                    )
            elif path_shaped:
                raise ValueError(f"Local model path '{repo_id}' does not exist.")
        # A local pipeline pick must be a diffusers directory (model_index.json), else it would only fail after eviction.
        if kind == "pipeline":
            root = Path(repo_id).expanduser()
            # Gate on .exists() (not .is_dir()) so a local FILE picked as a pipeline is rejected too.
            indexes = (
                ("model_index.json", "modular_model_index.json")
                if fam.modular_workflow
                else ("model_index.json",)

View on GitHub (pinned to 203007d190)

Solutions

Use model_kind='single_file' if the file is .safetensors.
If you intend a GGUF load, pass the .gguf file's path (or its directory + gguf_filename).
Make the client derive model_kind from the file's suffix.

Example fix

# before
load(repo_id='/models/denoiser.safetensors', model_kind='gguf')

# after
load(repo_id='/models/denoiser.safetensors', model_kind='single_file')

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
root = Path(repo_id).expanduser()
if root.is_file() and model_kind == 'gguf' and root.suffix.lower() != '.gguf':
    model_kind = 'single_file' if root.suffix.lower() == '.safetensors' else None

Type guard

def local_file_kind_ok(repo_id: str, kind: str) -> bool:
    root = Path(repo_id).expanduser()
    return not root.is_file() or not (kind == 'gguf' and root.suffix.lower() != '.gguf')

Prevention

When passing a local file path, set model_kind from the file's suffix.
Prefer directory + gguf_filename over raw file paths for GGUF loads.

When it happens

Trigger: load(repo_id='/models/denoiser.safetensors', model_kind='gguf') — repo_id is an existing file whose suffix lowercased is not .gguf.

Common situations: Passing a single downloaded safetensors file with the GGUF kind copied from another workflow; mislabeling a pickle .ckpt as gguf; drag-and-drop paths from a file manager mapping to the wrong kind.

Related errors

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