unslothai/unsloth · error · ValueError

{exc}

Error message

{exc}

What it means

A re-raise wrapper: when repo_id is a local DIRECTORY and resolving gguf_filename inside it (resolve_local_gguf_child) throws — typically because the named checkpoint does not exist in the directory — the original exception is converted into a ValueError so the API reports it as a client input error (HTTP 4xx semantics) instead of a server fault. The message text is whatever the resolver said.

Source

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

                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":
                    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()

View on GitHub (pinned to 203007d190)

Solutions

  1. List the directory and pass the exact filename present on disk (case-sensitive).
  2. Re-download or re-quantize so the expected filename exists.
  3. Point gguf_filename at the file you actually have rather than the hub's canonical name.

Example fix

# before
load(repo_id='/data/wan25', model_kind='gguf', gguf_filename='Wan2.5-Q4_K_M.gguf')
# FileNotFoundError: no such child

# after
# ls /data/wan25 -> wan2.5-i2v-Q4_K_M.gguf
load(repo_id='/data/wan25', model_kind='gguf', gguf_filename='wan2.5-i2v-Q4_K_M.gguf')
Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
root = Path(repo_id).expanduser()
if root.is_dir():
    target = (root / gguf_filename)
    if not target.is_file():
        names = [p.name for p in root.iterdir() if p.suffix.lower() == '.gguf']
        raise FileNotFoundError(f'{gguf_filename!r} not in {repo_id}; have: {names}')

Type guard

def checkpoint_in_dir(repo_id: str, gguf_filename: str) -> bool:
    root = Path(repo_id).expanduser()
    return not root.is_dir() or (root / gguf_filename).is_file()

Try / catch

try:
    load(...)
except ValueError as e:
    if 'not found' in str(e).lower() or 'no such' in str(e).lower():
        # list directory contents and prompt the user to re-pick
        raise
    raise

Prevention

When it happens

Trigger: load(repo_id='/data/models/wan25', model_kind='gguf', gguf_filename='Wan2.5-Q8.gguf') where that file is absent from the directory (wrong name, different quant, file moved).

Common situations: Local model folders whose filenames differ from hub names (renamed after download); stale caches after re-quantizing; typos in quant suffixes (Q4_K_M vs Q4KM); directory shared across machines with partial sync.

Related errors

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