invoke-ai/InvokeAI · info · NotAMatchError

ambiguous 16-channel PiD checkpoint; defaulting to FLUX.1

Error message

ambiguous 16-channel PiD checkpoint; defaulting to FLUX.1

What it means

FLUX.1, SD3 and Qwen-Image decoders are architecturally identical (16-channel latent), so weights alone cannot separate them. If neither an explicit `base` override nor a filename names one, only the FLUX config can accept the file; the SD3 and Qwen-Image classes raise this `NotAMatchError`, which resolves the tie by defaulting to FLUX.1.

Source

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

        """
        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):
    """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.")

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Install with an explicit `base` override (e.g. `base='stable-diffusion-3'`) to pin the correct backbone
2. Rename the file or directory to include the backbone name (e.g. `PiD_res2k_sr4x_official_sd3_distill_4step`) so identification can read it
3. Accept the FLUX.1 default if the decoder is genuinely interchangeable (identical weights) — but know the recorded base will be Flux

Example fix

// before
install('model_ema_bf16.pth')            # ambiguous -> defaults to Flux
// after
install('model_ema_bf16.pth', base='stable-diffusion-3')

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)
if sd[key].shape[1] == 16:
    print('16ch checkpoint: FLUX.1/SD3/Qwen-Image are identical; pass an explicit base to avoid the FLUX.1 default.')

try:
    install_model(path)  # ambiguous 16ch -> defaults to Flux
except NotAMatchError:
    install_model(path, base='stable-diffusion-3')  # pin explicitly

When it happens

Trigger: `_validate_base` with `latent_channels=16`, no `base` override, and `named_base=None` (no name component matches a backbone pattern) — evaluated by the SD3/Qwen-Image/Flux2 config classes.

Common situations: Single-file local install where NVIDIA's directory name is dropped (file is just `model_ema_bf16.pth`) and the user did not pass `base`; renamed checkpoint files.

Related errors

• name indicates {named_base}, not {expected_base}
• Unrecognized LLLite module name: '{name}'
• transformer is SDNQ-quantized; use Main_SDNQ_Diffusers_FLUX_
• directory is not a full FLUX.2 pipeline (no model_index.json
• transformer is SDNQ-quantized; use Main_SDNQ_Diffusers_Flux2

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