unslothai/unsloth · error · ValueError

Family '{fam.name}' has no native sd.cpp asset mapping.

Error message

Family '{fam.name}' has no native sd.cpp asset mapping.

What it means

ValueError raised when the family was detected but that family has no native sd.cpp asset mapping — the engine knows the family yet has no GGUF/text-encoder/VAE asset spec for it, so a native load is impossible.

Source

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

            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
        # companions too -- and here that means the repos _asset_specs actually FETCHES. The
        # native engine does not read the diffusers base: FLUX.2 takes its VAE from
        # unsloth/FLUX.2-VAE and its encoders from another repo again, so recording only the base
        # left every repo the pick really depends on outside the guard, and an unloaded model's
        # encoder could be deleted while its GGUF stayed installed. Best-effort bookkeeping;
        # never fails a load.

View on GitHub (pinned to 203007d190)

Solutions

  1. Run the load on the diffusers (GPU) engine for that family instead.
  2. Pick a different GGUF checkpoint from a family that does have a native mapping (see the supported native families).
  3. If you expected native support, check the backend version — the mapping may have been added later.
Defensive patterns

Strategy: fallback

Validate before calling

from core.inference.diffusion_families import detect_family_for_pick

fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
if fam is None or not family_sd_cpp_supported(fam):
    route_to_diffusers_engine(repo_id)  # no native mapping for this family

Try / catch

try:
    backend.begin_load(repo_id=r, gguf_filename=f)
except ValueError as e:
    if 'no native sd.cpp asset mapping' in str(e):
        return diffusers_backend.load(r)
    raise

Prevention

When it happens

Trigger: begin_load selecting a family that is supported on diffusers but has no sd.cpp mapping (family_sd_cpp_supported(fam) is False).

Common situations: Switching a working diffusers model to the native engine because a CPU/low-VRAM host was chosen; family_override forcing a family whose native mapping does not exist.

Related errors

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