unslothai/unsloth · error · ValueError

'{fam.name}' checkpoints are whole-pipeline single files and

Error message

'{fam.name}' checkpoints are whole-pipeline single files and have no GGUF transformer variant; load the .safetensors pipeline instead of a GGUF.

What it means

Raised before any GPU handoff when the requested load kind is 'gguf' but the detected family has single_file_is_pipeline set - its checkpoints are whole-pipeline .safetensors single files (no separate GGUF transformer variant exists). The check runs in the cheap validation phase specifically so the failure happens before the resident chat model is evicted.

Source

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

            excluded = excluded_model_reason(repo_id)
            if excluded:
                raise ValueError(f"'{repo_id}' cannot be loaded: {excluded}")
            raise ValueError(
                f"'{repo_id}' is not a supported diffusion image model. Supported families: "
                f"{', '.join(supported_family_names())}. If this is a variant of one of them, "
                f"pass family_override with that family name. (Video models and image models "
                f"whose diffusers transformer has no single-file loader are not supported.)"
            )
        # Refuse a too-old diffusers here, not deep in the load, but only when this load builds the diffusers pipeline: a
        # GGUF this host routes to native sd.cpp never instantiates the class. The picker gate reads the same predicate.
        # Imported here, not at module import, because the router imports this module's siblings.
        from .diffusion_engine_router import family_buildable_here

        if not family_buildable_here(fam, model_kind = kind):
            assert_pipeline_class_available(fam.pipeline_class, fam.name)
        # Families whose single file IS the whole pipeline have no GGUF path; reject before eviction.
        if kind == "gguf" and fam.single_file_is_pipeline:
            raise ValueError(
                f"'{fam.name}' checkpoints are whole-pipeline single files and have no GGUF "
                f"transformer variant; load the .safetensors pipeline instead of a GGUF."
            )
        # A multi-denoiser family (Ideogram 4) has no transformer-only path; reject before eviction.
        if kind in ("gguf", "single_file") and fam.pipeline_only:
            raise ValueError(
                f"'{fam.name}' loads only as a full diffusers pipeline (it assembles "
                f"multiple transformers), not from a single-file or GGUF checkpoint; "
                f"select the pipeline repo."
            )
        # Non-GGUF loads fetch + deserialise weights, so gate to unsloth/ or a local path.
        if kind != "gguf" and not _is_trusted_diffusion_repo(repo_id):
            raise ValueError(
                f"Non-GGUF diffusion loads are restricted to unsloth/* repos (or a local "
                f"path); got '{repo_id}'. Pass a gguf_filename to load a GGUF instead."
            )
        # The companion base repo also loads via from_pretrained, so it must clear the same trust bar.
        if base_repo and base_repo.strip() and not _is_trusted_diffusion_repo(base_repo):

View on GitHub (pinned to 203007d190)

Solutions

Load the family's .safetensors pipeline single file instead: pass model_kind='single_file' (or unset) with the .safetensors filename.
Pick the full pipeline repo for that family and drop the gguf parameters entirely.
If you need a quantized transformer, choose a different family that does ship GGUF transformer variants.

Example fix

# before: no GGUF variant exists for this family
manager.validate_load_request(repo_id="org/Family",
    model_kind="gguf", gguf_filename="transformer-Q4.gguf")

# after: load the whole-pipeline single file
manager.validate_load_request(repo_id="org/Family",
    model_kind="single_file", gguf_filename="family-full.safetensors")

Defensive patterns

Strategy: validation

Validate before calling

fam = manager.detect_family_for_pick(repo_id)
if fam is not None and fam.single_file_is_pipeline:
    allowed_kinds = {"single_file", "pipeline"}  # no gguf for this family

Try / catch

try:
    fam = manager.validate_load_request(repo_id=r, model_kind=k, gguf_filename=f)
except ValueError as e:
    if "no GGUF transformer variant" in str(e):
        retry_as_single_file_safetensors(r)
    else:
        raise

Prevention

Read the family's flags (single_file_is_pipeline) from the model metadata before offering a GGUF option.
Never default model_kind to 'gguf' globally - default per family based on what it actually ships.
Keep this preflight in the request path: it is what prevents the chat-model eviction before an impossible load.

When it happens

Trigger: Calling validate_load_request / load with model_kind='gguf' (or a gguf_filename that resolves kind to gguf) for a family flagged single_file_is_pipeline, e.g. attempting a GGUF transformer load of a family that only ships complete pipeline files.

Common situations: User sees a family supported in the picker and assumes GGUF quantizations exist for it like they do for other families; a UI default or saved preset sets model_kind='gguf'; mixing up a family's single-file .safetensors format with the GGUF ecosystem.

Related errors

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