invoke-ai/InvokeAI · error · NotImplementedError

CheckpointConfigBase is not implemented for Z-Image models.

Error message

CheckpointConfigBase is not implemented for Z-Image models.

What it means

Z-Image models are only supported from diffusers-style directories/single-file, not from raw checkpoint configs (CheckpointConfigBase, i.e. a single .safetensors/.ckpt with a config file). The loader raises NotImplementedError to state explicitly that this config format is unsupported, instead of attempting a conversion that does not exist.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/z_image.py:148

            continue

        # For all other keys, just copy as-is
        new_sd[key] = value

    return new_sd


@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.Main, format=ModelFormat.Diffusers)
class ZImageDiffusersModel(GenericDiffusersLoader):
    """Class to load Z-Image main models (Z-Image-Turbo, Z-Image-Base, Z-Image-Edit)."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if isinstance(config, Checkpoint_Config_Base):
            raise NotImplementedError("CheckpointConfigBase is not implemented for Z-Image models.")

        if submodel_type is None:
            raise Exception("A submodel type must be provided when loading main pipelines.")

        model_path = Path(config.path)
        submodel_path = resolve_submodel_path(config, submodel_type, model_path / submodel_type.value)

        # Check if submodel folder has SDNQ quantization - if so, use SDNQ loader
        if self._is_sdnq_folder(submodel_path):
            if submodel_type == SubModelType.TextEncoder:
                return self._load_sdnq_text_encoder(submodel_path)
            elif submodel_type == SubModelType.Transformer:
                return self._load_sdnq_transformer(submodel_path)

        load_class = self.get_hf_load_class(model_path, submodel_type)
        repo_variant = config.repo_variant if isinstance(config, Diffusers_Config_Base) else None
        variant = repo_variant.value if repo_variant else None

View on GitHub (pinned to 0b6a024f2f)

Solutions

Re-install the model as a diffusers folder (or the supported single-file format) rather than a checkpoint config.
Convert the checkpoint to diffusers format with a conversion script, then re-import the resulting folder.
Delete the model record and re-add it, selecting the correct source format so a non-checkpoint config is created.

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager.config import Checkpoint_Config_Base
if isinstance(config, Checkpoint_Config_Base):
    raise ValueError("Re-import this Z-Image model as a diffusers folder; checkpoint configs are unsupported")

Type guard

from invokeai.backend.model_manager.config import Checkpoint_Config_Base

def is_checkpoint_config(config) -> bool:
    return isinstance(config, Checkpoint_Config_Base)

Try / catch

try:
    model = loader._load_model(config, submodel_type)
except NotImplementedError as e:
    if "CheckpointConfigBase" in str(e):
        raise RuntimeError("Convert the Z-Image checkpoint to diffusers format and re-import it") from e
    raise

Prevention

When adding Z-Image models, choose the diffusers-folder (or supported single-file) source, not checkpoint.
Never point a Z-Image record at a bare .ckpt/.safetensors with a YAML config.
Check config type with isinstance before calling the loader in custom tooling.

When it happens

Trigger: Installing/registering a Z-Image model as a checkpoint (Checkpoint Config) in the model manager and then loading it, causing isinstance(config, Checkpoint_Config_Base) to be True in _load_model.

Common situations: User added a bare .safetensors Z-Image file via 'Add Model' choosing the checkpoint path; converted-model metadata mislabels the format; older model-manager records after the Z-Image loader was added.

Related errors

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