invoke-ai/InvokeAI · error · ValueError

Only CheckpointConfigBase models are supported here.

Error message

Only CheckpointConfigBase models are supported here.

What it means

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.

Source

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

@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint)
class ZImageControlCheckpointModel(ModelLoader):
    """Class to load Z-Image Control adapter models from safetensors checkpoint.

    Z-Image Control models are standalone adapters containing control layers
    (control_layers, control_all_x_embedder, control_noise_refiner) that can be
    combined with a base ZImageTransformer2DModel at runtime for spatial conditioning
    (Canny, HED, Depth, Pose, MLSD).
    """

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if not isinstance(config, Checkpoint_Config_Base):
            raise ValueError("Only CheckpointConfigBase models are supported here.")

        # ControlNet type models don't use submodel_type - load the adapter directly
        return self._load_control_adapter(config)

    def _load_control_adapter(
        self,
        config: AnyModelConfig,
    ) -> AnyModel:
        from safetensors.torch import load_file

        from invokeai.backend.z_image.z_image_control_adapter import ZImageControlAdapter

        assert isinstance(config, ControlNet_Checkpoint_ZImage_Config)
        model_path = Path(config.path)

        # Load the safetensors state dict
        sd = load_file(model_path)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Re-register/re-scan the model so its config is created with ModelFormat.Checkpoint, producing a Checkpoint_Config_Base-derived config.
2. Fix the model record (models.yaml or DB) so the format matches the files on disk (checkpoint single-file vs diffusers folder).
3. If using a custom config class, make it inherit from Checkpoint_Config_Base.
4. Confirm the loader registry entry selected matches the model's actual format.

Example fix

// before (folder-format config reaching checkpoint loader)
config = Main_Model_Defaults(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Folder, path=...)
// after
config = Main_Model_Defaults(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint, path=...)
assert isinstance(config, Checkpoint_Config_Base)

from invokeai.backend.model_manager.config import Checkpoint_Config_Base
if not isinstance(config, Checkpoint_Config_Base):
    raise TypeError(f"ControlNet checkpoint loader needs Checkpoint_Config_Base, got {type(config).__name__}")

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

try:
    model = loader._load_model(config, submodel_type)
except ValueError as e:
    if "CheckpointConfigBase" in str(e):
        config = re_register_model_as_checkpoint(model_id)
        model = loader._load_model(config, submodel_type)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Only Qwen3Encoder_Checkpoint_Config models are supported her
• Expected Qwen3Encoder_Checkpoint_Config, got {type(config)._
• Only Qwen3Encoder_GGUF_Config models are supported here.
• Expected Qwen3Encoder_GGUF_Config, got {type(config).__name_
• Control weights must be within -1 to 2 range

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