{"record":{"id":"a06de20a7e0f1864","repo":"invoke-ai/InvokeAI","slug":"unsupported-z-image-model-format-transformer-con","errorCode":null,"errorMessage":"Unsupported Z-Image model format: {transformer_config.format}","messagePattern":"Unsupported Z-Image model format: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/z_image_denoise.py","lineNumber":444,"sourceCode":"\n            # For Heun scheduler, the number of actual steps may differ\n            num_scheduler_steps = len(scheduler.timesteps)\n        else:\n            num_scheduler_steps = total_steps\n\n        with ExitStack() as exit_stack:\n            # Get transformer config to determine if it's quantized\n            transformer_config = context.models.get_config(self.transformer.transformer)\n\n            # Determine if the model is quantized.\n            # If the model is quantized, then we need to apply the LoRA weights as sidecar layers. This results in\n            # slower inference than direct patching, but is agnostic to the quantization format.\n            if transformer_config.format in [ModelFormat.Diffusers, ModelFormat.Checkpoint]:\n                model_is_quantized = False\n            elif transformer_config.format in [ModelFormat.GGUFQuantized, ModelFormat.SDNQQuantized]:\n                model_is_quantized = True\n            else:\n                raise ValueError(f\"Unsupported Z-Image model format: {transformer_config.format}\")\n\n            # Load transformer - always use base transformer, control is handled via extension\n            (cached_weights, transformer) = exit_stack.enter_context(transformer_info.model_on_device())\n\n            # Prepare control extension if control is provided\n            control_extension: ZImageControlNetExtension | None = None\n\n            if self.control is not None:\n                # Load control adapter using context manager (proper GPU memory management)\n                control_model_info = context.models.load(self.control.control_model)\n                (_, control_adapter) = exit_stack.enter_context(control_model_info.model_on_device())\n                assert isinstance(control_adapter, ZImageControlAdapter)\n\n                # Get control_in_dim from adapter config (16 for V1, 33 for V2.0)\n                adapter_config = control_adapter.config\n                control_in_dim = adapter_config.get(\"control_in_dim\", 16)\n                num_control_blocks = adapter_config.get(\"num_control_blocks\", 6)\n","sourceCodeStart":426,"sourceCodeEnd":462,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/z_image_denoise.py#L426-L462","documentation":"Z-Image only knows how to load its transformer for Diffusers/Checkpoint (unquantized) and GGUF/SDNQ (quantized) model formats. Any other ModelFormat on the transformer config has no supported loading/patching path, so _run_diffusion raises ValueError with the offending format.","triggerScenarios":"Selecting a Z-Image main model whose ModelConfig.format is not one of Diffusers, Checkpoint, GGUFQuantized, or SDNQQuantized — invoke() then reaches the format switch in _run_diffusion and falls into the else branch.","commonSituations":"Pointing the model manager at a model converted with an unsupported tool (e.g. bnb quantization) or an exotic/custom format; a model-manager config whose format enum was set incorrectly; using a model file from a different architecture's pipeline.","solutions":["Install/convert the Z-Image model to Diffusers, Checkpoint, GGUF, or SDNQ format","Fix the model's format field in the model manager config to match the actual on-disk format","Re-download the model from a source providing a supported format","Check InvokeAI version/update notes for newly supported Z-Image formats"],"exampleFix":"// before\n# model config: format = 'BnbQuantized'\ntransformer_info = context.models.get_by_key(z_image_model_key)\n// after\n# convert/reconfigure model so format in {Diffusers, Checkpoint, GGUFQuantized, SDNQQuantized}\ntransformer_info = context.models.get_by_key(z_image_model_key)","handlingStrategy":"validation","validationCode":"from invokeai.backend.model_manager.config import ModelFormat\nSUPPORTED = {ModelFormat.Diffusers, ModelFormat.Checkpoint, ModelFormat.GGUFQuantized, ModelFormat.SDNQQuantized}\nconfig = context.models.get_config(z_image_model_key)\nassert config.format in SUPPORTED, f\"Unsupported Z-Image format: {config.format}\"","typeGuard":"def is_supported_zimage_format(cfg) -> bool:\n    return cfg.format in {ModelFormat.Diffusers, ModelFormat.Checkpoint, ModelFormat.GGUFQuantized, ModelFormat.SDNQQuantized}","tryCatchPattern":"try:\n    output = denoise.invoke(context)\nexcept ValueError as e:\n    if \"Unsupported Z-Image model format\" in str(e):\n        raise ModelFormatError(\"convert the model to Diffusers/Checkpoint/GGUF/SDNQ\") from e\n    raise","preventionTips":["Only install Z-Image checkpoints from sources with supported formats","Verify the model-manager format field matches the file after conversion","Keep InvokeAI updated for newly supported quantization formats"],"tags":["model-format","z-image","unsupported"],"backgroundTag":"unsupported-model-format","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}