{"record":{"id":"da8d54622b3ee665","repo":"unslothai/unsloth","slug":"gguf-name-is-a-flux2-inner-dims-get-got-f-f","errorCode":null,"errorMessage":"'{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.","messagePattern":"'(.+?)' is a (.+?)'\\)\\} checkpoint, but it is being loaded against '(.+?)', which is (.+?)'\\)\\}\\. Pass base_repo for the matching variant, or pick the GGUF that matches the selected model\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/diffusion_compat.py","lineNumber":379,"sourceCode":"        got,\n        want,\n    )\n\n\ndef assert_flux2_pick_compatible(\n    fam: Any,\n    repo_id: str,\n    gguf_filename: Optional[str],\n    base_repo: Optional[str],\n    hf_token: Optional[str] = None,\n) -> None:\n    \"\"\"Refuse an incompatible FLUX.2 pick before anything is downloaded or unloaded.\n\n    ``ValueError``, like every other unloadable-pick refusal: /images/load maps it to 400 and\n    ``/images/download-plan`` catches it, whereas a RuntimeError escapes the plan as a bare 500.\"\"\"\n    reason = flux2_pick_mismatch(fam, repo_id, gguf_filename, base_repo, hf_token)\n    if reason is not None:\n        raise ValueError(reason)\n\n\ndef _reset_inner_dim_cache() -> None:\n    \"\"\"Drop the memoised header probes. Tests only.\"\"\"\n    with _CACHE_LOCK:\n        _INNER_DIM_CACHE.clear()\n","sourceCodeStart":361,"sourceCodeEnd":386,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/diffusion_compat.py#L361-L386","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass base_repo matching the GGUF variant (the message names both the checkpoint's variant and the base's).","Or pick the GGUF file that matches the currently selected base model variant.","Check the GGUF filename/header variant before queuing the download."],"exampleFix":"# before\nPOST /images/load {\"repo_id\": \"flux2-ggufs\", \"gguf_filename\": \"FLUX.2-dev-Klein-Q4_K_M.gguf\"}\n# base_repo defaults to full FLUX.2 -> inner_dim mismatch\n# after\nPOST /images/load {\n  \"repo_id\": \"flux2-ggufs\",\n  \"gguf_filename\": \"FLUX.2-dev-Klein-Q4_K_M.gguf\",\n  \"base_repo\": \"black-forest-labs/FLUX.2-dev-Klein\"\n}","handlingStrategy":"try-catch","validationCode":"from core.inference.diffusion_compat import flux2_pick_mismatch\n\nreason = flux2_pick_mismatch(fam, repo_id, gguf_filename, base_repo, hf_token)\nif reason is not None:\n    raise UserError(reason)  # before queueing any download","typeGuard":null,"tryCatchPattern":"try:\n    engine.load(repo_id=repo, gguf_filename=gguf, base_repo=base)\nexcept ValueError as e:\n    if \"checkpoint\" in str(e) and \"base_repo\" in str(e):\n        # message names the matching base: re-ask the user or map variant -> base_repo\n        base = VARIANT_BASE_MAP[variant_of(gguf)]\n        engine.load(repo_id=repo, gguf_filename=gguf, base_repo=base)\n    else:\n        raise","preventionTips":["Always send base_repo explicitly when loading FLUX.2 GGUF variants (Klein/schnell vs full).","Pin GGUF filename and base_repo together in model presets so they cannot be mixed.","Run flux2_pick_mismatch() before the download-plan call to fail before bandwidth is spent."],"tags":["diffusion","gguf","flux2","model-loading","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}