{"record":{"id":"5b1a22607db11edf","repo":"invoke-ai/InvokeAI","slug":"ambiguous-16-channel-pid-checkpoint-defaulting-to","errorCode":null,"errorMessage":"ambiguous 16-channel PiD checkpoint; defaulting to FLUX.1","messagePattern":"ambiguous 16-channel PiD checkpoint; defaulting to FLUX\\.1","errorType":"exception","errorClass":"NotAMatchError","httpStatus":null,"severity":"info","filePath":"invokeai/backend/model_manager/configs/pid_decoder.py","lineNumber":370,"sourceCode":"        \"\"\"\n        expected_base = cls.model_fields[\"base\"].default\n        # Guaranteed present: an unsupported channel count was rejected outright before this ran.\n        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","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/pid_decoder.py#L352-L388","documentation":"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.","triggerScenarios":"`_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.","commonSituations":"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.","solutions":["Install with an explicit `base` override (e.g. `base='stable-diffusion-3'`) to pin the correct backbone","Rename the file or directory to include the backbone name (e.g. `PiD_res2k_sr4x_official_sd3_distill_4step`) so identification can read it","Accept the FLUX.1 default if the decoder is genuinely interchangeable (identical weights) — but know the recorded base will be Flux"],"exampleFix":"// before\ninstall('model_ema_bf16.pth')            # ambiguous -> defaults to Flux\n// after\ninstall('model_ema_bf16.pth', base='stable-diffusion-3')","handlingStrategy":"fallback","validationCode":"import torch\nsd = torch.load(ckpt_path, map_location='cpu')\nkey = next(k for k in sd if 'lq_proj' in k and 'latent_proj' in k)\nif sd[key].shape[1] == 16:\n    print('16ch checkpoint: FLUX.1/SD3/Qwen-Image are identical; pass an explicit base to avoid the FLUX.1 default.')","typeGuard":null,"tryCatchPattern":"try:\n    install_model(path)  # ambiguous 16ch -> defaults to Flux\nexcept NotAMatchError:\n    install_model(path, base='stable-diffusion-3')  # pin explicitly","preventionTips":["Keep NVIDIA's directory name (PiD_res2k_sr4x_official_<backbone>_...) when doing single-file installs","Pass an explicit `base` override for 16-channel decoders","Name files/directories to include the backbone (sd3, qwen-image, flux)"],"tags":["model-identification","ambiguity","naming"],"backgroundTag":"ambiguous-model-identification","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}