invoke-ai/InvokeAI · warning · NotAMatchError

state dict does not look like a Z-Image model

Error message

state dict does not look like a Z-Image model

What it means

_validate_looks_like_z_image_model loads the model's state dict and checks for Z-Image-specific keys (_has_z_image_keys); if none are found it raises NotAMatchError. This prevents the Z-Image checkpoint config from claiming arbitrary single-file weights that happen to land in the scan path. Identification then falls through to other config classes.

Source

Thrown at invokeai/backend/model_manager/configs/main.py:1435

    @classmethod
    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:
        raise_if_not_file(mod)

        raise_for_override_fields(cls, override_fields)

        cls._validate_looks_like_z_image_model(mod)

        cls._validate_does_not_look_like_gguf_quantized(mod)

        variant = override_fields.pop("variant", None) or ZImageVariantType.Turbo

        return cls(**override_fields, variant=variant)

    @classmethod
    def _validate_looks_like_z_image_model(cls, mod: ModelOnDisk) -> None:
        has_z_image_keys = _has_z_image_keys(mod.load_state_dict())
        if not has_z_image_keys:
            raise NotAMatchError("state dict does not look like a Z-Image model")

    @classmethod
    def _validate_does_not_look_like_gguf_quantized(cls, mod: ModelOnDisk) -> None:
        has_ggml_tensors = _has_ggml_tensors(mod.load_state_dict())
        if has_ggml_tensors:
            raise NotAMatchError("state dict looks like GGUF quantized")


class Main_GGUF_ZImage_Config(Checkpoint_Config_Base, Main_Config_Base, Config_Base):
    """Model config for GGUF-quantized Z-Image transformer models."""

    base: Literal[BaseModelType.ZImage] = Field(default=BaseModelType.ZImage)
    format: Literal[ModelFormat.GGUFQuantized] = Field(default=ModelFormat.GGUFQuantized)
    variant: ZImageVariantType = Field()

    @classmethod
    def from_model_on_disk(cls, mod: ModelOnDisk, override_fields: dict[str, Any]) -> Self:
        raise_if_not_file(mod)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Verify the file is an authentic Z-Image checkpoint from the official release; re-download if truncated.
2. Check that the checkpoint wasn't key-renamed by a conversion script; re-run the official conversion.
3. Import the file as the model type it actually is instead of forcing Z-Image classification.

from safetensors import safe_open

Z_IMAGE_KEY_MARKERS = ("layers.", "z_image", "transformer.blocks")

def looks_like_z_image(path: str) -> bool:
    with safe_open(path, framework="pt") as f:
        return any(any(m in k for m in Z_IMAGE_KEY_MARKERS) for k in list(f.keys())[:200])

def is_z_image_state_dict(state_dict: dict) -> bool:
    return any("z_image" in k or k.startswith("model.diffusion_model.layers") for k in state_dict.keys())

try:
    cfg = Main_Checkpoint_ZImage_Config.from_model_on_disk(mod)
except NotAMatchError:
    # state dict isn't Z-Image; re-check provenance of the file
    cfg = None

When it happens

Trigger: from_model_on_disk -> _validate_looks_like_z_image_model on a checkpoint/safetensors file whose state dict contains no Z-Image transformer keys, during Z-Image main-model identification.

Common situations: Importing a renamed/repurposed safetensors file (e.g. a Flux or Qwen checkpoint renamed to z-image), a truncated download that lost most tensors, or an unsupported re-pack of the model that renamed keys.

Related errors

• transformer is SDNQ-quantized; use Main_SDNQ_Diffusers_ZImag
• state dict does not look like a Qwen3 model
• state dict bundles a Qwen-VL visual tower; this is a Qwen-VL
• state dict looks like GGUF quantized
• state dict looks SDNQ-quantized; use Qwen3Encoder_SDNQ_Folde

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/15daee481ec6f137. Report an issue: GitHub.