unslothai/unsloth · error · ValueError

'{fam.name}' loads only as a full diffusers pipeline (it ass

Error message

'{fam.name}' loads only as a full diffusers pipeline (it assembles multiple transformers), not from a single-file or GGUF checkpoint; select the pipeline repo.

What it means

Raised when the load kind is 'gguf' or 'single_file' but the detected family has pipeline_only set - multi-denoiser families (the comment names Ideogram 4) assemble multiple transformers and have no transformer-only load path at all. Like the sibling checks it runs pre-eviction so the resident GPU model is not lost to a doomed load.

Source

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

                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):
            raise ValueError(
                f"base_repo is restricted to unsloth/* repos (or a local path); got '{base_repo}'."
            )
        # A local base_repo loads as a full pipeline; reject a non-pipeline one before eviction.
        _assert_local_base_is_pipeline(base_repo)
        # Reject a bad LOCAL pick before the route evicts chat: a path-shaped repo_id must be on disk.

View on GitHub (pinned to 203007d190)

Solutions

Select the full pipeline repo for this family and drop gguf_filename / single-file mode.
To reduce memory use on a pipeline-only family, use memory_mode / offload settings instead of transformer-only loading.
If a single-file path is a hard requirement, choose a family that supports it.

Example fix

# before: transformer-only load of a pipeline-only family
manager.validate_load_request(repo_id="org/Ideogram-4",
    model_kind="gguf", gguf_filename="t-Q8.gguf")
# ValueError: ... loads only as a full diffusers pipeline ...

# after: select the pipeline repo
manager.validate_load_request(repo_id="org/Ideogram-4", model_kind="pipeline")

Defensive patterns

Strategy: validation

Validate before calling

fam = manager.detect_family_for_pick(repo_id)
if fam is not None and fam.pipeline_only:
    assert not gguf_filename and model_kind not in ("gguf", "single_file")

Try / catch

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

Prevention

For multi-denoiser families, expose only memory_mode/offload controls - there is no transformer-only path to offer.
Validate kind against the family's flags before submitting so the UI never sends an impossible combination.
Do not treat this as retriable: the family structure, not the environment, is the blocker.

When it happens

Trigger: Calling the load validation with model_kind in ('gguf','single_file') (explicitly, or via a gguf_filename) for a pipeline_only family such as a multi-denoiser model.

Common situations: User tries to save VRAM by loading only the transformer of a model that needs all of its denoisers; saved preset from another family carries a single-file/gguf mode into a pipeline-only pick; model listing mixes single-file and pipeline-only families without labelling the difference.

Related errors

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