{"record":{"id":"615a4a0c412f6353","repo":"invoke-ai/InvokeAI","slug":"checkpointconfigbase-is-not-implemented-for-z-imag","errorCode":null,"errorMessage":"CheckpointConfigBase is not implemented for Z-Image models.","messagePattern":"CheckpointConfigBase is not implemented for Z-Image models\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":148,"sourceCode":"            continue\n\n        # For all other keys, just copy as-is\n        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","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from invokeai.backend.model_manager.config import Checkpoint_Config_Base\nif isinstance(config, Checkpoint_Config_Base):\n    raise ValueError(\"Re-import this Z-Image model as a diffusers folder; checkpoint configs are unsupported\")","typeGuard":"from invokeai.backend.model_manager.config import Checkpoint_Config_Base\n\ndef is_checkpoint_config(config) -> bool:\n    return isinstance(config, Checkpoint_Config_Base)","tryCatchPattern":"try:\n    model = loader._load_model(config, submodel_type)\nexcept NotImplementedError as e:\n    if \"CheckpointConfigBase\" in str(e):\n        raise RuntimeError(\"Convert the Z-Image checkpoint to diffusers format and re-import it\") from e\n    raise","preventionTips":["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."],"tags":["python","notimplemented","model-loading","unsupported-format"],"backgroundTag":"unsupported-model-format","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}