unslothai/unsloth · error · ValueError

'{repo_id}' is not a supported diffusion image model. Suppor

Error message

'{repo_id}' is not a supported diffusion image model. Supported families: {supported_family_names}. If this is a variant of one of them, pass family_override with that family name. (Video models and image models whose diffusers transformer has no single-file loader are not supported.)

What it means

The fallback refusal when family detection returns None AND the repo is not on the exclusion list - the id simply does not match any supported family name or alias as a whole-segment token. The message lists supported families and suggests family_override for true variants, and notes the two structural gaps: video models and image models whose diffusers transformer has no single-file loader.

Source

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

        gguf_filename: Optional[str] = None,
        family_override: Optional[str] = None,
        model_kind: Optional[str] = None,
        base_repo: Optional[str] = None,
    ) -> DiffusionFamily:
        """Cheap, network-free validation shared by the route (before it evicts the
        chat model) and the load paths, so an unloadable pick fails BEFORE the GPU
        handoff. Resolves the load kind (gguf / single_file / pipeline), then raises
        ValueError for a missing single-file name, a non-unsloth non-GGUF repo, or an
        undetectable family, and ValueError/FileNotFoundError for a bad local path.
        Touches no GPU, network, or state."""
        kind = resolve_model_kind(gguf_filename, model_kind)
        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
        if fam is None:
            # An excluded model gets its stated reason, not the unknown-family message that invites a doomed retry.
            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."
            )

View on GitHub (pinned to 203007d190)

Solutions

Check the supported families listed in the message and pick a repo whose id contains one of those family tokens.
If the checkpoint really is a variant of a supported family, pass family_override='<family name>' with the load.
Fix typos or follow a rename: resolve the repo's current id on huggingface.co and retry.
If the model is genuinely new/unsupported, update the backend (family table) or wait for support - no parameter combination will load it.

Example fix

# before: id contains no supported family token
manager.validate_load_request(repo_id="someorg/brand-new-model")
# ValueError: ... is not a supported diffusion image model ...

# after: variant of a supported family -> explicit override
manager.validate_load_request(repo_id="someorg/brand-new-model",
                              family_override="qwen-image")

Defensive patterns

Strategy: validation

Validate before calling

from core.inference.diffusion_families import detect_family, supported_family_names

def family_known(repo_id: str, override: str | None = None) -> bool:
    return detect_family(repo_id, override) is not None

Try / catch

try:
    fam = manager.validate_load_request(repo_id=repo_id, family_override=ov)
except ValueError as e:
    if "not a supported diffusion image model" in str(e):
        suggest_supported_repos(supported_family_names())
    else:
        raise

Prevention

Build pickers from supported_family_names() instead of free-text repo entry.
When a new model generation ships, check whether the family table needs an entry before users hit this.
Use family_override only for genuine variants; a wrong override moves the failure deeper into the load.
Remember video models are structurally out of scope for the image loader - route them to the video pipeline.

When it happens

Trigger: validate_load_request with a repo_id whose lowercased name contains no supported family token (longest-segment match against _FAMILIES names/aliases fails), e.g. a brand-new model family, a renamed repo, or a typo in the id.

Common situations: A new image model shipped after this backend's family table was written; repo renamed on Hugging Face so the family keyword disappeared from the id; typo ('sdx1' instead of 'sdxl'); user attempts to load a video model through the image pipeline.

Related errors

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