{"record":{"id":"fc9f73548c004516","repo":"invoke-ai/InvokeAI","slug":"name-indicates-named-base-not-expected-base","errorCode":null,"errorMessage":"name indicates {named_base}, not {expected_base}","messagePattern":"name indicates (.+?), not (.+?)","errorType":"exception","errorClass":"NotAMatchError","httpStatus":null,"severity":"info","filePath":"invokeai/backend/model_manager/configs/pid_decoder.py","lineNumber":373,"sourceCode":"        candidate_bases = _LATENT_CHANNELS_TO_BASES[latent_channels]\n\n        if expected_base not in candidate_bases:\n            raise NotAMatchError(f\"latent channels={latent_channels} do not match backbone {expected_base}\")\n        if len(candidate_bases) == 1 or had_base_override:\n            return\n\n        # A name pointing outside the family — a 16-channel file called \"sdxl\" — contradicts the\n        # weights and is discarded rather than obeyed. Obeying it would have all three 16ch classes\n        # reject the file, leaving a perfectly good decoder to the `Unknown_Config` fallback.\n        if named_base not in candidate_bases:\n            named_base = None\n\n        if named_base is None:\n            if expected_base is not BaseModelType.Flux:\n                raise NotAMatchError(\"ambiguous 16-channel PiD checkpoint; defaulting to FLUX.1\")\n            return\n        if named_base is not expected_base:\n            raise NotAMatchError(f\"name indicates {named_base}, not {expected_base}\")\n\n\nclass PiDDecoder_Checkpoint_FLUX_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):\n    \"\"\"PiD decoder for the FLUX.1 backbone (16-channel latent).\"\"\"\n\n    base: Literal[BaseModelType.Flux] = Field(default=BaseModelType.Flux)\n    variant: PiDDecoderVariantType = Field(description=\"Resolution preset of the PiD decoder checkpoint.\")\n\n\nclass PiDDecoder_Checkpoint_Flux2_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):\n    \"\"\"PiD decoder for the FLUX.2 backbone (128-channel latent).\"\"\"\n\n    base: Literal[BaseModelType.Flux2] = Field(default=BaseModelType.Flux2)\n    variant: PiDDecoderVariantType = Field(description=\"Resolution preset of the PiD decoder checkpoint.\")\n\n\nclass PiDDecoder_Checkpoint_SD3_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):\n    \"\"\"PiD decoder for the Stable Diffusion 3 backbone (16-channel latent).\"\"\"","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/pid_decoder.py#L355-L391","documentation":"When the checkpoint's name names a backbone inside the candidate family but the config class being tried pins a different one, `_validate_base` raises `NotAMatchError` ('name indicates X, not Y'). A name outside the candidate family is discarded (weights win), but a name inside it is trusted over this class's default.","triggerScenarios":"`_validate_base` reaches `named_base is not expected_base` — e.g. a 16-channel checkpoint named `...sd3...` evaluated by the FLUX or Qwen-Image config class; equally the FLUX class rejects a file named `qwen_image`.","commonSituations":"Multi-backbone downloads kept in their original NVIDIA directory names; a user override or rename conflicts with what the weights/name say; only a final problem if no class matches (e.g. name says sd3 but you overrode base='qwen-image').","solutions":["Remove or correct a conflicting `base` override so it matches the name/weights","Rename the file/directory so the backbone name reflects the actual decoder","If the name is wrong and the weights are what matter, supply the correct `base` override — an explicit override outranks the name"],"exampleFix":"// before: directory named PiD_..._sd3_... but install override base='flux'\ninstall(path, base='flux')\n// after\ninstall(path, base='stable-diffusion-3')  # or omit base and trust the name","handlingStrategy":"validation","validationCode":"import re\ndef named_backbone(path: str) -> str | None:\n    text = path.lower()\n    for pat, base in [(r'flux[_\\-.]?2','flux2'), (r'sdxl','sdxl'), (r'qwen[_\\-.]?image','qwen-image'), (r'sd[_\\-.]?3','sd3'), (r'flux','flux')]:\n        if re.search(pat, text):\n            return base\n    return None\n# ensure any `base` override matches named_backbone(path)","typeGuard":null,"tryCatchPattern":"try:\n    install_model(path, base=override)\nexcept NotAMatchError as e:\n    if 'name indicates' in str(e):\n        logger.error('Base override conflicts with checkpoint name: %s', e)\n    else:\n        raise","preventionTips":["Keep the `base` override consistent with the checkpoint's directory/file name","Don't rename multi-backbone downloads out of NVIDIA's naming scheme","Omit the base override and trust auto-identification when unsure"],"tags":["model-identification","naming","override-conflict"],"backgroundTag":"ambiguous-model-identification","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}