unslothai/unsloth · error · ValueError

'{gguf_name}' is a {_FLUX2_INNER_DIMS.get(got, f'FLUX.2 vari

Error message

'{gguf_name}' is a {_FLUX2_INNER_DIMS.get(got, f'FLUX.2 variant with inner_dim {got}')} checkpoint, but it is being loaded against '{base_repo}', which is {_FLUX2_INNER_DIMS.get(want, f'inner_dim {want}')}. Pass base_repo for the matching variant, or pick the GGUF that matches the selected model.

What it means

A FLUX.2 GGUF checkpoint's inner dimension (read from the GGUF header, cached) is compared against the inner_dim of the base repo it would be loaded against (base_repo, or the family default). A mismatch — e.g. a FLUX.2 [dev] smaller-variant GGUF against the full FLUX.2 base — means the transformer weights cannot fit the base model's structure, so the pick is refused as ValueError before anything is downloaded or the resident model is unloaded. ValueError is deliberate: /images/load maps it to 400 and /images/download-plan catches it, whereas a RuntimeError would escape as a 500.

Source

Thrown at studio/backend/core/inference/diffusion_compat.py:379

        got,
        want,
    )


def assert_flux2_pick_compatible(
    fam: Any,
    repo_id: str,
    gguf_filename: Optional[str],
    base_repo: Optional[str],
    hf_token: Optional[str] = None,
) -> None:
    """Refuse an incompatible FLUX.2 pick before anything is downloaded or unloaded.

    ``ValueError``, like every other unloadable-pick refusal: /images/load maps it to 400 and
    ``/images/download-plan`` catches it, whereas a RuntimeError escapes the plan as a bare 500."""
    reason = flux2_pick_mismatch(fam, repo_id, gguf_filename, base_repo, hf_token)
    if reason is not None:
        raise ValueError(reason)


def _reset_inner_dim_cache() -> None:
    """Drop the memoised header probes. Tests only."""
    with _CACHE_LOCK:
        _INNER_DIM_CACHE.clear()

View on GitHub (pinned to 203007d190)

Solutions

1. Pass base_repo matching the GGUF variant (the message names both the checkpoint's variant and the base's).
2. Or pick the GGUF file that matches the currently selected base model variant.
3. Check the GGUF filename/header variant before queuing the download.

Example fix

# before
POST /images/load {"repo_id": "flux2-ggufs", "gguf_filename": "FLUX.2-dev-Klein-Q4_K_M.gguf"}
# base_repo defaults to full FLUX.2 -> inner_dim mismatch
# after
POST /images/load {
  "repo_id": "flux2-ggufs",
  "gguf_filename": "FLUX.2-dev-Klein-Q4_K_M.gguf",
  "base_repo": "black-forest-labs/FLUX.2-dev-Klein"
}

from core.inference.diffusion_compat import flux2_pick_mismatch

reason = flux2_pick_mismatch(fam, repo_id, gguf_filename, base_repo, hf_token)
if reason is not None:
    raise UserError(reason)  # before queueing any download

try:
    engine.load(repo_id=repo, gguf_filename=gguf, base_repo=base)
except ValueError as e:
    if "checkpoint" in str(e) and "base_repo" in str(e):
        # message names the matching base: re-ask the user or map variant -> base_repo
        base = VARIANT_BASE_MAP[variant_of(gguf)]
        engine.load(repo_id=repo, gguf_filename=gguf, base_repo=base)
    else:
        raise

When it happens

Trigger: Selecting a FLUX.2 GGUF quant whose inner_dim differs from the selected base_repo's inner_dim (or the family default base when base_repo is omitted) — e.g. mixing a Klein/schnell-variant GGUF with the full-size base repo.

Common situations: Downloading a smaller FLUX.2 variant GGUF for VRAM reasons but leaving base_repo at the default; HF repos publishing multiple variants under similar names; picking GGUFs by file size without checking the variant.

Related errors

• a single-file checkpoint name is required for a '{kind}' loa
• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• Local model path does not exist: {repo_id}
• '{repo_id}' is a single-file GGUF repo; load it with model_k

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