invoke-ai/InvokeAI · info · NotAMatchError

latent channels={latent_channels} do not match backbone {exp

Error message

latent channels={latent_channels} do not match backbone {expected_base}

What it means

Each PiD config class pins `base` to one backbone. `_validate_base` compares the class's pinned backbone against the set of backbones compatible with the checkpoint's latent channel count; an SDXL config examining a 16-channel file (or FLUX.2 examining 16ch, etc.) raises `NotAMatchError`, which just means 'not this backbone' while another class claims the file.

Source

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

        four of the five classes are supposed to say about every valid checkpoint. The reasons that
        would rule out all five are raised in ``from_model_on_disk`` before this runs.

        The latent channel count is authoritative and is the only thing separating SDXL (4ch) and
        FLUX.2 (128ch) from the 16ch family. FLUX.1, SD3 and Qwen-Image are architecturally
        identical, so within that family, in order of how much the evidence can be trusted:

        - an explicit ``base`` override wins outright. ``raise_for_override_fields`` has already
          validated it against this class's ``Literal``, so it names exactly one of the five, and
          whoever set it knows more than a filename anyone can write;
        - failing that, a name component naming exactly one of the three decides;
        - failing that, the family defaults to FLUX.1.
        """
        expected_base = cls.model_fields["base"].default
        # Guaranteed present: an unsupported channel count was rejected outright before this ran.
        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):

View on GitHub (pinned to 0b6a024f2f)

Solutions

If identification ultimately fails, pass an explicit `base` override matching the checkpoint's true backbone
Verify the checkpoint's latent channel count (dim 1 of `lq_proj.latent_proj.0.weight`) and use the matching config (4=SDXL, 16=FLUX.1/SD3/Qwen-Image, 128=FLUX.2)
If this error is the only one raised and the file is valid, ensure you are on a recent InvokeAI version where another class will claim it

Example fix

// before
install(path)  # auto-detect
// after
install(path, base='flux')  # for a 16-channel FLUX.1 decoder

Defensive patterns

Strategy: try-catch

Validate before calling

import torch
sd = torch.load(ckpt_path, map_location='cpu')
key = next(k for k in sd if 'lq_proj' in k and 'latent_proj' in k)
ch = sd[key].shape[1]
base = {4: 'sdxl', 16: 'flux', 128: 'flux2'}.get(ch)
# install with base=base (for 16ch, pick flux/sd3/qwen-image explicitly)

Try / catch

try:
    install_model(path)
except NotAMatchError:
    pass  # expected during identification: another backbone class claims the file

Prevention

Pass an explicit `base` override matching the checkpoint's backbone
Remember this error is normal when other config classes evaluate the file
Read dim 1 of lq_proj.latent_proj.0.weight to learn the true backbone (4=SDXL, 16=16ch family, 128=FLUX.2)

When it happens

Trigger: Raised inside `_validate_base` when `expected_base not in _LATENT_CHANNELS_TO_BASES[latent_channels]` — e.g. the SDXL config class evaluates a 16-channel FLUX-family checkpoint during multi-class identification.

Common situations: Normal during identification of any 16ch (FLUX.1/SD3/Qwen-Image) or other-family checkpoint: four of the five classes will raise this by design. Only a problem if it surfaces as the final error, i.e. no class matched at all.

Related errors

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