invoke-ai/InvokeAI · info · NotAMatchError

name indicates {named_base}, not {expected_base}

Error message

name indicates {named_base}, not {expected_base}

What it means

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.

Source

Thrown at invokeai/backend/model_manager/configs/pid_decoder.py:373

        candidate_bases = _LATENT_CHANNELS_TO_BASES[latent_channels]

        if expected_base not in candidate_bases:
            raise NotAMatchError(f"latent channels={latent_channels} do not match backbone {expected_base}")
        if len(candidate_bases) == 1 or had_base_override:
            return

        # A name pointing outside the family — a 16-channel file called "sdxl" — contradicts the
        # weights and is discarded rather than obeyed. Obeying it would have all three 16ch classes
        # reject the file, leaving a perfectly good decoder to the `Unknown_Config` fallback.
        if named_base not in candidate_bases:
            named_base = None

        if named_base is None:
            if expected_base is not BaseModelType.Flux:
                raise NotAMatchError("ambiguous 16-channel PiD checkpoint; defaulting to FLUX.1")
            return
        if named_base is not expected_base:
            raise NotAMatchError(f"name indicates {named_base}, not {expected_base}")


class PiDDecoder_Checkpoint_FLUX_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):
    """PiD decoder for the FLUX.1 backbone (16-channel latent)."""

    base: Literal[BaseModelType.Flux] = Field(default=BaseModelType.Flux)
    variant: PiDDecoderVariantType = Field(description="Resolution preset of the PiD decoder checkpoint.")


class PiDDecoder_Checkpoint_Flux2_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):
    """PiD decoder for the FLUX.2 backbone (128-channel latent)."""

    base: Literal[BaseModelType.Flux2] = Field(default=BaseModelType.Flux2)
    variant: PiDDecoderVariantType = Field(description="Resolution preset of the PiD decoder checkpoint.")


class PiDDecoder_Checkpoint_SD3_Config(PiDDecoder_Checkpoint_Config_Base, Config_Base):
    """PiD decoder for the Stable Diffusion 3 backbone (16-channel latent)."""

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Remove or correct a conflicting `base` override so it matches the name/weights
  2. Rename the file/directory so the backbone name reflects the actual decoder
  3. If the name is wrong and the weights are what matter, supply the correct `base` override — an explicit override outranks the name

Example fix

// before: directory named PiD_..._sd3_... but install override base='flux'
install(path, base='flux')
// after
install(path, base='stable-diffusion-3')  # or omit base and trust the name
Defensive patterns

Strategy: validation

Validate before calling

import re
def named_backbone(path: str) -> str | None:
    text = path.lower()
    for pat, base in [(r'flux[_\-.]?2','flux2'), (r'sdxl','sdxl'), (r'qwen[_\-.]?image','qwen-image'), (r'sd[_\-.]?3','sd3'), (r'flux','flux')]:
        if re.search(pat, text):
            return base
    return None
# ensure any `base` override matches named_backbone(path)

Try / catch

try:
    install_model(path, base=override)
except NotAMatchError as e:
    if 'name indicates' in str(e):
        logger.error('Base override conflicts with checkpoint name: %s', e)
    else:
        raise

Prevention

When it happens

Trigger: `_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`.

Common situations: 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').

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/fc9f73548c004516. Report an issue: GitHub.