unslothai/unsloth · error · ValueError

'{repo_id}' is a single-file GGUF repo; load it with model_k

Error message

'{repo_id}' is a single-file GGUF repo; load it with model_kind 'gguf' and a .gguf filename, not as a full pipeline.

What it means

Heuristic rejection of a common misload: the repo id ends in '-GGUF' (case-insensitive), which marks Hugging Face single-file GGUF repos, but the request is a pipeline load (no gguf_filename, non-path id). Such repos contain quantized .gguf files rather than a diffusers layout, so a pipeline from_pretrained would fail after eviction; the validation refuses it up front with the correct invocation spelled out.

Source

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

            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:
                raise FileNotFoundError(f"Local model path does not exist: {repo_id}")
            elif repo_id.upper().endswith("-GGUF"):
                # A remote "*-GGUF" id is not a pipeline; reject here instead of evicting chat then failing.
                raise ValueError(
                    f"'{repo_id}' is a single-file GGUF repo; load it with model_kind 'gguf' "
                    f"and a .gguf filename, not as a full pipeline."
                )
        return fam

    def preflight_base_access(
        self,
        repo_id: str,
        fam: Optional[DiffusionFamily],
        *,
        gguf_filename: Optional[str] = None,
        model_kind: Optional[str] = None,
        base_repo: Optional[str] = None,
        hf_token: Optional[str] = None,
    ) -> None:
        """The gated/unreadable-base and FLUX.2 size-pairing refusals, run by the route BEFORE it
        takes the GPU.

View on GitHub (pinned to 203007d190)

Solutions

1. Load the GGUF repo the intended way: model_kind='gguf' plus a .gguf filename from that repo (e.g. 'flux1-dev-Q4_K_S.gguf').
2. Or switch to the base pipeline repo (drop the -GGUF suffix / use the original org's repo or its unsloth mirror).
3. List the -GGUF repo's files to pick the quantization level you want as the checkpoint name.

Example fix

# before
manager.validate_load_request(repo_id="city96/FLUX.1-dev-gguf")
# ValueError: ... is a single-file GGUF repo; load it with model_kind 'gguf' ...

# after
manager.validate_load_request(repo_id="city96/FLUX.1-dev-gguf",
    model_kind="gguf", gguf_filename="flux1-dev-Q4_K_S.gguf")

def looks_like_gguf_repo(repo_id: str) -> bool:
    return repo_id.upper().endswith("-GGUF")

try:
    fam = manager.validate_load_request(repo_id=r)
except ValueError as e:
    if "single-file GGUF repo" in str(e):
        list_gguf_files_and_switch_mode(r)
    else:
        raise

When it happens

Trigger: Passing an id like 'org/Model-GGUF' or 'city96/FLUX.1-dev-gguf' as a pipeline load (no model_kind, no gguf_filename) - typically copy-pasting a GGUF repo link straight from Hugging Face into a pipeline field.

Common situations: User browses HF, finds the -GGUF republish ranked first in search, and pastes it where a pipeline repo belongs; UI search surfaces GGUF repos without indicating they need the GGUF load mode.

Related errors

• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• a 'pipeline' load takes a full diffusers repo, not a single-
• '{fam.name}' checkpoints are whole-pipeline single files and
• a single-file checkpoint name is required for a '{kind}' loa

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