unslothai/unsloth · error · ValueError

a 'pipeline' load takes a full diffusers repo, not a single-

Error message

a 'pipeline' load takes a full diffusers repo, not a single-file name.

What it means

A 'pipeline' load takes a full diffusers repo (or local pipeline directory), not an individual checkpoint file: this ValueError fires when the kind resolved to pipeline but a gguf_filename was still supplied. The two parameters are mutually exclusive by kind, and the cheap validation catches the contradiction before GPU eviction.

Source

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

            # 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:
                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(

View on GitHub (pinned to 203007d190)

Solutions

Drop gguf_filename for a pipeline load - the whole repo (or local directory with model_index.json) is the unit.
If you want that single file loaded, set model_kind to 'single_file' (for .safetensors) or 'gguf' (for .gguf).
Fix the client so kind and filename fields are cleared together when the mode changes.

Example fix

# before
manager.validate_load_request(repo_id="unsloth/FLUX.1-dev",
    model_kind="pipeline", gguf_filename="t-Q4.gguf")

# after: pipeline takes the repo only
manager.validate_load_request(repo_id="unsloth/FLUX.1-dev", model_kind="pipeline")

Defensive patterns

Strategy: validation

Validate before calling

kind = resolve_model_kind(gguf_filename, model_kind)
if kind == "pipeline":
    gguf_filename = None  # pipeline takes the repo, not a file

Try / catch

try:
    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)
except ValueError as e:
    if "takes a full diffusers repo" in str(e):
        manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=None)
    else:
        raise

Prevention

Model kind and checkpoint filename are one coupled pair in the request - always set or clear them together.
In UIs, changing the load mode should clear the file field (and vice versa).
Reject requests where resolve_model_kind contradicts the presence of gguf_filename before they reach the backend.

When it happens

Trigger: model_kind='pipeline' (explicitly, or resolved from defaults) together with a non-empty gguf_filename - e.g. a UI that sends both fields because the user picked a file then switched the mode to pipeline.

Common situations: Client reuses one request struct for all load kinds and leaves stale fields populated; user changed mode after picking a file; preset merging concatenates options from different kinds.

Related errors

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