What causes "'{repo_id}' cannot be loaded: {excluded}" in unslothai/unsloth?

Read the reason in the message - it states why this exact variant is unsupported (usually 'needs an input image / different pipeline').

unslothai/unsloth · error · ValueError

'{repo_id}' cannot be loaded: {excluded}

Error message

'{repo_id}' cannot be loaded: {excluded}

What it means

Raised by the network-free load validation when family detection returned None and the repo id matches an entry in the _EXCLUDED_MODELS table (matched by whole-segment tokens, so 'kontext' does not match 'kontextual'). Excluded models get their specific stated reason - e.g. an editing/inpaint/layered checkpoint whose transformer needs an extra input - instead of the generic unknown-family message that would invite a doomed retry.

Source

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

        *,
        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

Read the reason in the message - it states why this exact variant is unsupported (usually 'needs an input image / different pipeline').
Pick the base (non-edit, non-inpaint, non-layered) checkpoint of the same family instead.
If the variant genuinely is a plain checkpoint with a misleading name, pass family_override with the supported family name to bypass detection.
Do not retry the same id unchanged - exclusion is deliberate and will not resolve on a second attempt.

Example fix

# before: edit variant -> ValueError("'org/qwen-image-edit' cannot be loaded: ...")
fam = manager.validate_load_request(repo_id="org/Qwen-Image-Edit-2511")

# after: base checkpoint of the same family
fam = manager.validate_load_request(repo_id="org/Qwen-Image")

Defensive patterns

Strategy: validation

Validate before calling

from core.inference.diffusion_families import excluded_model_reason

def pick_is_loadable(repo_id: str) -> bool:
    return excluded_model_reason(repo_id) is None  # plus family detection for full check

Try / catch

try:
    fam = manager.validate_load_request(repo_id=repo_id, model_kind=kind, gguf_filename=fn)
except ValueError as e:
    if "cannot be loaded" in str(e):
        show_reason_and_suggest_base_checkpoint(repo_id)
    else:
        raise

Prevention

Filter edit/inpaint/layered variants out of model pickers (keywords: edit, kontext, inpaint, layered) unless you implement their input contract.
Run validate_load_request on every pick before switching models - it is network-free and cheap.
Read the exclusion reason verbatim to the user; it states the structural gap, not a transient failure.
Do not offer family_override as a workaround for excluded models - the override only helps misdetected variants of plain checkpoints.

When it happens

Trigger: Calling validate_load_request (or the load route that calls it) with a repo_id containing an excluded token - e.g. 'qwen-image-edit', '*-inpaint', 'Qwen-Image-Layered' - without a family_override that resolves to a supported family.

Common situations: User browses Hugging Face and picks an edit/inpaint variant of a supported base model (Kontext, layered, inpaint checkpoints share the arch keyword) assuming the base family support covers it; model lists surface variants that the loader cannot feed the extra input image to.

Related errors

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