{"record":{"id":"5fb3a45c6a3d0ef0","repo":"invoke-ai/InvokeAI","slug":"a-submodel-type-must-be-provided-when-loading-main-5fb3a4","errorCode":null,"errorMessage":"A submodel type must be provided when loading main pipelines.","messagePattern":"A submodel type must be provided when loading main pipelines\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":151,"sourceCode":"        new_sd[key] = value\n\n    return new_sd\n\n\n@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.Main, format=ModelFormat.Diffusers)\nclass ZImageDiffusersModel(GenericDiffusersLoader):\n    \"\"\"Class to load Z-Image main models (Z-Image-Turbo, Z-Image-Base, Z-Image-Edit).\"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,\n    ) -> AnyModel:\n        if isinstance(config, Checkpoint_Config_Base):\n            raise NotImplementedError(\"CheckpointConfigBase is not implemented for Z-Image models.\")\n\n        if submodel_type is None:\n            raise Exception(\"A submodel type must be provided when loading main pipelines.\")\n\n        model_path = Path(config.path)\n        submodel_path = resolve_submodel_path(config, submodel_type, model_path / submodel_type.value)\n\n        # Check if submodel folder has SDNQ quantization - if so, use SDNQ loader\n        if self._is_sdnq_folder(submodel_path):\n            if submodel_type == SubModelType.TextEncoder:\n                return self._load_sdnq_text_encoder(submodel_path)\n            elif submodel_type == SubModelType.Transformer:\n                return self._load_sdnq_transformer(submodel_path)\n\n        load_class = self.get_hf_load_class(model_path, submodel_type)\n        repo_variant = config.repo_variant if isinstance(config, Diffusers_Config_Base) else None\n        variant = repo_variant.value if repo_variant else None\n\n        # Z-Image prefers bfloat16, but use safe dtype based on target device capabilities.\n        target_device = TorchDevice.choose_torch_device()\n        dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L133-L169","documentation":"_load_model needs a SubModelType to know which submodel (text encoder, VAE, transformer, tokenizer) of the Z-Image pipeline to resolve and return; with submodel_type None there is nothing to resolve, so it raises Exception. Main-pipeline loading is decomposed into per-submodel loads, each of which must state its type.","triggerScenarios":"Calling ZImageLoader._load_model(config) without submodel_type, or a dispatch path that drops the SubModelType when loading Z-Image main pipelines.","commonSituations":"Direct calls to _load_model in custom scripts; refactors or third-party integrations that assumed a single-file checkpoint loader signature (where submodel_type is optional); generic loader wrappers that pass only the config.","solutions":["Pass the desired SubModelType, e.g. _load_model(config, SubModelType.Transformer).","Use the ModelManager/ModelLoaderRegistry entry points so submodel types are supplied automatically per submodel load.","Note the earlier CheckpointConfigBase check: also ensure the config is not a checkpoint config or you will hit the NotImplementedError first."],"exampleFix":"// before\ntransformer = loader._load_model(config)\n\n// after\nfrom invokeai.backend.model_manager.taxonomy import SubModelType\ntransformer = loader._load_model(config, SubModelType.Transformer)","handlingStrategy":"validation","validationCode":"if submodel_type is None:\n    raise ValueError(\"submodel_type is required when loading Z-Image main pipelines\")","typeGuard":"def has_submodel_type(st: SubModelType | None) -> bool:\n    return st is not None","tryCatchPattern":"try:\n    model = loader._load_model(config, submodel_type)\nexcept Exception as e:\n    if \"A submodel type must be provided\" in str(e):\n        raise RuntimeError(\"Pass SubModelType when loading Z-Image pipelines, or use ModelManager.load_model\") from e\n    raise","preventionTips":["Always pass SubModelType when invoking _load_model on Z-Image configs.","Prefer ModelManager/ModelLoaderRegistry APIs which supply submodel types automatically.","Check the config is not a CheckpointConfigBase before loading (that check precedes this one)."],"tags":["python","exception","model-loading","invalid-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}