unslothai/unsloth · error · ValueError

'{'repo_id'}' has no native sd.cpp asset mapping.

Error message

'{'repo_id'}' has no native sd.cpp asset mapping.

What it means

ValueError from the planning API when the family cannot be detected or has no native sd.cpp asset mapping. The comment notes it is unreachable through the route (which only plans for picks the native engine would accept); it exists so direct callers get the same message begin_load would raise.

Source

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

        diffusers backend returns, so the Hub download manager stages what sd-cli will actually
        open.

        The two engines want different files: diffusers builds a pipeline around the base repo's
        sharded components, while sd-cli reads the single-file VAE + text encoders declared in
        ``diffusion_families``. Planning with the wrong engine stages tens of GB the load never
        opens and then pulls the native assets inline, outside the manager's progress and disk
        preflight -- so the route asks whichever engine it predicts the load will select.

        The diffusers-only kwargs (quant / memory / LoRA) are accepted and ignored, exactly as
        ``begin_load`` accepts them: nothing sd-cli fetches depends on them."""
        if not gguf_filename:
            raise ValueError(
                "gguf_filename is required: the native engine loads single-file GGUF checkpoints only."
            )
        fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
        if fam is None or not family_sd_cpp_supported(fam):
            # Unreachable through the route, but a direct caller gets the same message begin_load would raise.
            raise ValueError(f"'{repo_id}' has no native sd.cpp asset mapping.")

        specs = self._asset_specs(
            repo_id,
            gguf_filename,
            fam,
            self._flux2_inner_dim(repo_id, gguf_filename, fam, hf_token),
        )
        by_repo = self._assets_by_repo(specs)

        # STAGED before the load runs, so each entry must name the repo _fetch_assets will pull
        # from: some asset repos are gated (the FLUX.1 VAE lives in black-forest-labs/FLUX.1-schnell)
        # and an anonymous user would 401 at staging, never reaching the swap. Same per-repo file
        # list on both sides, so both take the same decision.
        fetch_repo = _fetch_repo_map(specs, hf_token)
        # MERGED, not reassigned: two upstream repos can share one fetch repo (the FLUX.2 VAE and
        # the dev encoders both come from Comfy-Org/flux2-dev once that repack is cached), and a
        # plain comprehension would drop whichever landed first, leaving its files out of both the
        # staged entry and the footprint.

View on GitHub (pinned to 203007d190)

Solutions

  1. Plan/load only native-supported families (those with an sd.cpp asset mapping).
  2. Fix family_override or the repo pick so detection yields a native-supported family.
  3. Use the diffusers planner for diffusers-engine models.
Defensive patterns

Strategy: validation

Validate before calling

fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
if fam is None or not family_sd_cpp_supported(fam):
    raise ValueError(f'{repo_id}: not plannable on the native engine')

Try / catch

try:
    plan = backend.plan_assets(repo_id=r, gguf_filename=f)
except ValueError as e:
    if 'no native sd.cpp asset mapping' in str(e):
        plan = diffusers_planner(r)
    raise

Prevention

When it happens

Trigger: Direct call to the planning API with an unsupported repo/family or a family without an sd.cpp mapping.

Common situations: Plugins/MCP tools planning downloads for a diffusers-only model; family_override misuse.

Related errors

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