{"record":{"id":"2c3968fb69bf321b","repo":"invoke-ai/InvokeAI","slug":"unexpected-submodel-requested-for-pid-decoder","errorCode":null,"errorMessage":"Unexpected submodel requested for PiD decoder.","messagePattern":"Unexpected submodel requested for PiD decoder\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/pid_decoder.py","lineNumber":57,"sourceCode":"@ModelLoaderRegistry.register(base=BaseModelType.Flux, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\n@ModelLoaderRegistry.register(base=BaseModelType.Flux2, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\n@ModelLoaderRegistry.register(\n    base=BaseModelType.StableDiffusion3, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint\n)\n@ModelLoaderRegistry.register(\n    base=BaseModelType.StableDiffusionXL, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint\n)\n@ModelLoaderRegistry.register(base=BaseModelType.QwenImage, type=ModelType.PiDDecoder, format=ModelFormat.Checkpoint)\nclass PiDDecoderLoader(ModelLoader):\n    \"\"\"Loads a PiD checkpoint into a fully-constructed PidNet of the matching backbone.\"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,\n    ) -> AnyModel:\n        if submodel_type is not None:\n            raise ValueError(\"Unexpected submodel requested for PiD decoder.\")\n\n        # Backbone is encoded in the config's `base` field — populated by\n        # PiDDecoder_Checkpoint_*_Config when the user added the model.\n        backbone: BaseModelType = config.base\n\n        raw_sd = strip_net_prefix(_load_raw_checkpoint(Path(config.path)))\n\n        # Build the live PidNet on CPU and pour the checkpoint in — then drop\n        # the dict so we don't hold two copies in RAM at once.\n        pid_net = load_pid_decoder(raw_sd, backbone)\n        del raw_sd\n\n        # We deliberately keep PidNet's parameters in float32 here. PiD\n        # consumes Gemma-2 hidden states that contain large outliers\n        # (per-token max well past 100) and the in-network RMSNorm\n        # (`variance = hidden_states.pow(2).mean(-1, keepdim=True)`) loses\n        # precision badly in bf16, producing all-NaN outputs. The decode\n        # wrapper runs the forward pass under `torch.autocast(bf16)` so the","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/pid_decoder.py#L39-L75","documentation":"PiD decoders are self-contained models, not pipeline components: PiDDecoderLoader._load_model requires submodel_type to be None and raises ValueError if any submodel is requested. The backbone (Flux/SD3/SDXL/QwenImage) is taken from config.base, so there is nothing per-submodel to load.","triggerScenarios":"Pipeline-assembly or generic loading code that requests a SubModelType (e.g. SubModelType.UNet or VAE) while loading a ModelType.PiDDecoder record, or direct _load_model calls that pass a non-None submodel.","commonSituations":"Code that iterates all submodel types for every model in a pipeline; treating the PiD decoder like a main model with subfolders; test scripts reusing main-model loading helpers.","solutions":["Load PiD decoder models with submodel_type=None (omit the argument).","Exclude ModelType.PiDDecoder from generic per-submodel loading loops.","Read config.base if you need to know which backbone the decoder targets.","Call the higher-level decode wrapper rather than treating the decoder as a pipeline submodel."],"exampleFix":"// before\npid = loader._load_model(cfg, SubModelType.Vae)  # ValueError\n// after\npid = loader._load_model(cfg)  # submodel_type must be None","handlingStrategy":"validation","validationCode":"if submodel_type is not None:\n    raise ValueError(\"PiD decoders are standalone: call with submodel_type=None\")\npid = loader._load_model(cfg)  # backbone comes from cfg.base","typeGuard":null,"tryCatchPattern":"try:\n    pid = loader._load_model(cfg, submodel_type)\nexcept ValueError as e:\n    if \"Unexpected submodel requested for PiD decoder\" in str(e):\n        pid = loader._load_model(cfg)\n    else:\n        raise","preventionTips":["Exclude ModelType.PiDDecoder from per-submodel loading loops.","Always omit submodel_type when loading PiD decoders.","Use cfg.base to determine the decoder's target backbone."],"tags":["python","model-loading","submodel","invokeai"],"backgroundTag":"unexpected-submodel-requested","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}