{"record":{"id":"a12361d9914dc8e6","repo":"invoke-ai/InvokeAI","slug":"only-checkpointconfigbase-models-are-supported-her-a12361","errorCode":null,"errorMessage":"Only CheckpointConfigBase models are supported here.","messagePattern":"Only CheckpointConfigBase models are supported here\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":814,"sourceCode":"\n\n@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint)\nclass ZImageControlCheckpointModel(ModelLoader):\n    \"\"\"Class to load Z-Image Control adapter models from safetensors checkpoint.\n\n    Z-Image Control models are standalone adapters containing control layers\n    (control_layers, control_all_x_embedder, control_noise_refiner) that can be\n    combined with a base ZImageTransformer2DModel at runtime for spatial conditioning\n    (Canny, HED, Depth, Pose, MLSD).\n    \"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,\n    ) -> AnyModel:\n        if not isinstance(config, Checkpoint_Config_Base):\n            raise ValueError(\"Only CheckpointConfigBase models are supported here.\")\n\n        # ControlNet type models don't use submodel_type - load the adapter directly\n        return self._load_control_adapter(config)\n\n    def _load_control_adapter(\n        self,\n        config: AnyModelConfig,\n    ) -> AnyModel:\n        from safetensors.torch import load_file\n\n        from invokeai.backend.z_image.z_image_control_adapter import ZImageControlAdapter\n\n        assert isinstance(config, ControlNet_Checkpoint_ZImage_Config)\n        model_path = Path(config.path)\n\n        # Load the safetensors state dict\n        sd = load_file(model_path)\n","sourceCodeStart":796,"sourceCodeEnd":832,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L796-L832","documentation":"The Z-Image ControlNet checkpoint loader only accepts model configs deriving from Checkpoint_Config_Base. The model manager handed it a config object of a different kind (e.g. a diffusers-folder config or a GGUF config), which this loader cannot resolve into a checkpoint path/format, so it raises ValueError immediately.","triggerScenarios":"Model manager dispatches a Z-Image ControlNet load to ZImageControlCheckpointModel._load_model with a config that is not a Checkpoint_Config_Base subclass — typically a folder-format config registered with Checkpoint format, or a mismatched config class assigned to the model record.","commonSituations":"User converts a ControlNet between folder and checkpoint formats without re-scanning/re-registering the model; a manually edited models.yaml gives the wrong format field; a custom config class for Z-Image ControlNet that does not inherit Checkpoint_Config_Base.","solutions":["Re-register/re-scan the model so its config is created with ModelFormat.Checkpoint, producing a Checkpoint_Config_Base-derived config.","Fix the model record (models.yaml or DB) so the format matches the files on disk (checkpoint single-file vs diffusers folder).","If using a custom config class, make it inherit from Checkpoint_Config_Base.","Confirm the loader registry entry selected matches the model's actual format."],"exampleFix":"// before (folder-format config reaching checkpoint loader)\nconfig = Main_Model_Defaults(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Folder, path=...)\n// after\nconfig = Main_Model_Defaults(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint, path=...)\nassert isinstance(config, Checkpoint_Config_Base)","handlingStrategy":"type-guard","validationCode":"from invokeai.backend.model_manager.config import Checkpoint_Config_Base\nif not isinstance(config, Checkpoint_Config_Base):\n    raise TypeError(f\"ControlNet checkpoint loader needs Checkpoint_Config_Base, got {type(config).__name__}\")","typeGuard":"def is_checkpoint_config(config: AnyModelConfig) -> bool:\n    return isinstance(config, Checkpoint_Config_Base)","tryCatchPattern":"try:\n    model = loader._load_model(config, submodel_type)\nexcept ValueError as e:\n    if \"CheckpointConfigBase\" in str(e):\n        config = re_register_model_as_checkpoint(model_id)\n        model = loader._load_model(config, submodel_type)\n    else:\n        raise","preventionTips":["Register ControlNet models with format=Checkpoint so Checkpoint_Config_Base configs are created.","Re-scan models after converting between folder and single-file formats.","Ensure custom config classes inherit Checkpoint_Config_Base.","Spot-check models.yaml format fields after manual edits."],"tags":["invokeai","z-image","controlnet","config-type-mismatch"],"backgroundTag":"model-config-type-mismatch","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}