unslothai/unsloth · error · ValueError

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

Error message

'{'repo_id'}' is not a supported diffusion image model. Supported families: {', '.join(supported_family_names())}. If this is a variant of one of them, pass family_override with that family name.

What it means

ValueError raised when detect_family_for_pick(repo_id, gguf_filename, family_override) cannot match the pick to any supported diffusion family, even with the filename-fallback detector. The message lists the supported family names and suggests family_override for close variants.

Source

Thrown at studio/backend/core/inference/sd_cpp_backend.py:1195

        # Same fallback the diffusers and video backends take: the route ranks the selection and
        # passes the winner, but a direct caller (an MCP client, a test, a plugin) hands over
        # gpu_ids alone, and without this the native engine is the one engine that would drop the
        # pick silently. Re-ranked only when nobody has, so a route-resolved winner is never
        # second-guessed against free VRAM that has moved since.
        if gpu_ordinal is None:
            gpu_ordinal = (
                resolve_selected_cuda_ordinal(gpu_ids)
                if gpu_ids and resolve_diffusion_device_target().device == "cuda"
                else None
            )
        if not gguf_filename:
            raise ValueError(
                "gguf_filename is required: the native engine loads single-file GGUF checkpoints only."
            )
        # Filename-fallback detector (as the route validated) so a local .gguf whose family keyword lives only in the basename still loads.
        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
        if fam is None:
            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."
            )
        if not family_sd_cpp_supported(fam):
            raise ValueError(f"Family '{fam.name}' has no native sd.cpp asset mapping.")

        base = resolve_base_repo(fam, base_repo)
        # Offline-only here, and deliberately so. begin_load returns at once by contract -- the
        # route thread answers the UI with a status and the pull happens on the worker -- so it
        # cannot afford the range request's bound, let alone hold _lock across it and stall
        # status()/unload() for the same span. Memo or on-disk header or nothing. This value only
        # seeds the delete-cached guard's repo list below; the worker re-asks WITH the network and
        # refreshes that list, so the guard converges within one round trip of the load starting.
        inner_dim = self._flux2_inner_dim(
            repo_id, gguf_filename, fam, hf_token, allow_network = False
        )
        # Same link the diffusers resolver records, so the delete guard protects a native pick's

View on GitHub (pinned to 203007d190)

Solutions

Pass family_override with the supported family name the model actually is (e.g. 'flux', per the listed names).
Check the repo_id/gguf_filename spelling against supported families in the error message.
If the model is genuinely a new family, request support or use the diffusers engine if it covers it.

Example fix

# before
backend.begin_load(repo_id='my-mirror/some-renamed-model', gguf_filename='model-q8.gguf')

# after
backend.begin_load(repo_id='my-mirror/some-renamed-model', gguf_filename='model-q8.gguf', family_override='flux')

Defensive patterns

Strategy: validation

Validate before calling

from core.inference.diffusion_families import supported_family_names, detect_family_for_pick

names = supported_family_names()
fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
assert fam is not None, f'unsupported; pass family_override in {names}'

Try / catch

try:
    backend.begin_load(repo_id=r, gguf_filename=f)
except ValueError as e:
    if 'not a supported diffusion image model' in str(e):
        backend.begin_load(repo_id=r, gguf_filename=f, family_override='flux')
    else:
        raise

Prevention

Curate a whitelist of known repo_id -> family mappings in your client.
For mirrors/forks, record the family_override once instead of relying on name detection.

When it happens

Trigger: begin_load with a repo_id whose id and GGUF basename contain no supported family keyword; a re-named or forked model repo that is actually a supported family.

Common situations: Users pointing at mirrors/forks whose names omit the family keyword; newly published variants not yet in the supported list; typos in repo_id.

Related errors

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