unslothai/unsloth · error · ValueError

'{fam.name}' is a dual-expert model: a single {kind} file co

Error message

'{fam.name}' is a dual-expert model: a single {kind} file covers only one of its two transformers. Load the diffusers pipeline repo ('{fam.base_repo}') instead.

What it means

Raised when a dual-expert (fam.is_moe) family — one with two transformers, e.g. MiniMax-H3's video+audio experts — is loaded via model_kind 'gguf' or 'single_file'. A single checkpoint file carries only one of the two experts; the other would silently load dense bf16, defeating the quantization plan, so the loader refuses and points at the full diffusers pipeline repo (fam.base_repo).

Source

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

            raise ValueError(
                f"Non-GGUF video loads are limited to unsloth/* repos, the official "
                f"family base repos, and local paths; '{repo_id}' is neither."
            )
        # Companions load with from_pretrained, so a base repo is held to the non-GGUF bar: a GGUF pick must not smuggle in a remote base.
        if base_repo and (base_repo or "").strip() and not _is_trusted_video_repo(base_repo):
            raise ValueError(
                f"base_repo is limited to unsloth/* repos, the official family base "
                f"repos, and local paths; '{base_repo}' is neither."
            )
        # A local base_repo loads as a full pipeline (needs model_index.json); reject a non-pipeline one here, before the load.
        from core.inference.diffusion import _assert_local_base_is_pipeline

        _assert_local_base_is_pipeline(base_repo)
        if kind in ("gguf", "single_file") and not gguf_filename:
            raise ValueError("A gguf/single_file load needs the checkpoint filename.")
        if kind in ("gguf", "single_file") and fam.is_moe:
            # A single checkpoint carries one expert; the other would load dense bf16, off-plan.
            raise ValueError(
                f"'{fam.name}' is a dual-expert model: a single {kind} file covers only "
                f"one of its two transformers. Load the diffusers pipeline repo "
                f"('{fam.base_repo}') instead."
            )
        # A missing local checkpoint must fail HERE, before the route evicts a resident model.
        if kind in ("gguf", "single_file"):
            # Fail a kind/extension mismatch before the GPU handoff: gguf needs .gguf, single_file needs .safetensors.
            is_gguf_name = (gguf_filename or "").lower().endswith(".gguf")
            if kind == "gguf" and not is_gguf_name:
                raise ValueError("a 'gguf' load requires a .gguf checkpoint name.")
            if kind == "single_file" and is_gguf_name:
                raise ValueError("a .gguf checkpoint needs model_kind 'gguf', not 'single_file'.")
            if kind == "single_file" and not (gguf_filename or "").lower().endswith(".safetensors"):
                raise ValueError(
                    f"'{gguf_filename}' is not a loadable single-file checkpoint "
                    f"(expected a .safetensors name; use a .gguf name for a GGUF load)."
                )
            root = Path(repo_id).expanduser()

View on GitHub (pinned to 203007d190)

Solutions

Load the diffusers pipeline repo named in the message (fam.base_repo) with model_kind='pipeline'.
For quantization on that pipeline, use transformer_quant with a hosted pre-quantized scheme instead of a GGUF file.
UI: hide/disable gguf/single_file options for families flagged is_moe.

Example fix

# before
load(repo_id='minimax-h3', model_kind='gguf', gguf_filename='h3-video-Q4.gguf')

# after
load(repo_id=fam.base_repo, model_kind='pipeline', transformer_quant='fp8')

Defensive patterns

Strategy: validation

Validate before calling

if fam.is_moe and model_kind in ('gguf', 'single_file'):
    model_kind, gguf_filename = 'pipeline', None  # or reject up front

Type guard

def kind_allowed_for_family(fam, kind: str) -> bool:
    return kind not in ('gguf', 'single_file') or not fam.is_moe

Try / catch

try:
    load(...)
except ValueError as e:
    if 'dual-expert' in str(e):
        load(repo_id=fam.base_repo, model_kind='pipeline', ...)
    else:
        raise

Prevention

Check fam.is_moe before offering gguf/single_file options.
For MoE quantization, plan around hosted prequant schemes (transformer_quant), not GGUF files.

When it happens

Trigger: Calling load with model_kind='gguf' or 'single_file' on a family whose is_moe flag is set (a dual-expert model), regardless of filename validity.

Common situations: Applying the GGUF workflow习惯 from single-transformer families (Wan etc.) to a MoE family; a quantized single-file checkpoint of one expert circulating in the community and pasted into a config; UI not disabling the GGUF picker for MoE families.

Related errors

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