{"record":{"id":"fd80a78b106bd5c1","repo":"invoke-ai/InvokeAI","slug":"single-file-sdnq-z-image-checkpoints-only-provide","errorCode":null,"errorMessage":"Single-file SDNQ Z-Image checkpoints only provide the Transformer submodel. Received: {submodel_type.value if submodel_type else 'None'}","messagePattern":"Single-file SDNQ Z-Image checkpoints only provide the Transformer submodel\\. Received: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":601,"sourceCode":"    quantized weights live under ``transformer/`` alongside a ``config.json`` that\n    describes the architecture.\n    \"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,\n    ) -> AnyModel:\n        if not isinstance(config, (Main_SDNQ_ZImage_Config, Main_SDNQ_Diffusers_ZImage_Config)):\n            raise ValueError(\n                \"Only Main_SDNQ_ZImage_Config or Main_SDNQ_Diffusers_ZImage_Config models are supported here.\"\n            )\n\n        # Single-file SDNQ checkpoints only carry the transformer.\n        if isinstance(config, Main_SDNQ_ZImage_Config):\n            if submodel_type == SubModelType.Transformer:\n                return self._load_from_singlefile(config)\n            raise ValueError(\n                f\"Single-file SDNQ Z-Image checkpoints only provide the Transformer submodel. \"\n                f\"Received: {submodel_type.value if submodel_type else 'None'}\"\n            )\n\n        # Full ZImagePipeline folder — dispatch each submodel out of its own subfolder so the\n        # model can be used as a 'Qwen3 & VAE source model' for other Z-Image runs.\n        match submodel_type:\n            case SubModelType.Transformer:\n                return self._load_from_diffusers_folder(config)\n            case SubModelType.TextEncoder:\n                return self._load_text_encoder(config)\n            case SubModelType.Tokenizer:\n                return self._load_tokenizer(config)\n            case SubModelType.VAE:\n                return self._load_vae(config)\n\n        raise ValueError(\n            f\"Unsupported submodel type for SDNQ ZImagePipeline: {submodel_type.value if submodel_type else 'None'}\"","sourceCodeStart":583,"sourceCodeEnd":619,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L583-L619","documentation":"Single-file SDNQ Z-Image checkpoints physically contain only the transformer weights. When the config is Main_SDNQ_ZImage_Config, _load_model serves only SubModelType.Transformer; any other submodel (or None) raises this ValueError. Folder-based Main_SDNQ_Diffusers_ZImage_Config configs bypass this branch and dispatch all submodels.","triggerScenarios":"Calling _load_model with a Main_SDNQ_ZImage_Config and submodel_type other than SubModelType.Transformer — e.g. VAE, TextEncoder, Tokenizer — or leaving submodel_type as None; the loader framework probing available submodels.","commonSituations":"A pipeline install attempts to load the VAE or text encoder from a single-file SDNQ checkpoint; code assumes all SDNQ models are full pipeline folders; submodel auto-discovery iterates every SubModelType against a transformer-only checkpoint.","solutions":["Request only SubModelType.Transformer from the single-file SDNQ model.","Register a full SDNQ ZImagePipeline folder (Main_SDNQ_Diffusers_ZImage_Config) or another model as the VAE/text-encoder/tokenizer source and reference it in the pipeline.","Update caller logic to check the config type before probing submodels other than Transformer.","Convert the single-file checkpoint into a full pipeline folder if all submodels must come from one entry."],"exampleFix":"// before\nte = sdnq_loader._load_model(single_file_config, SubModelType.TextEncoder)  # ValueError\n// after\ntransformer = sdnq_loader._load_model(single_file_config, SubModelType.Transformer)\nte = sdnq_loader._load_model(folder_config, SubModelType.TextEncoder)  # from pipeline-folder model","handlingStrategy":"validation","validationCode":"if isinstance(config, Main_SDNQ_ZImage_Config) and submodel_type is not SubModelType.Transformer:\n    raise ValueError(\"single-file SDNQ Z-Image checkpoints only provide the Transformer submodel\")","typeGuard":"def sdnq_provides(config: AnyModelConfig, submodel_type: SubModelType | None) -> bool:\n    if isinstance(config, Main_SDNQ_ZImage_Config):\n        return submodel_type is SubModelType.Transformer\n    return submodel_type in (SubModelType.TextEncoder, SubModelType.Tokenizer, SubModelType.VAE)","tryCatchPattern":"try:\n    model = sdnq_loader._load_model(config, submodel_type)\nexcept ValueError as e:\n    if \"only provide the Transformer\" in str(e):\n        model = companion_loader._load_model(companion_config, submodel_type)\n    else:\n        raise","preventionTips":["Register a companion pipeline-folder or VAE-source model for single-file SDNQ checkpoints.","Check the config class before iterating all SubModelType values.","Only request the Transformer from single-file SDNQ entries."],"tags":["python","sdnq","submodel","model-loading","invokeai"],"backgroundTag":"unsupported-submodel-type","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}