invoke-ai/InvokeAI · error · Exception

A submodel type must be provided when loading main pipelines

Error message

A submodel type must be provided when loading main pipelines.

What it means

_load_model needs a SubModelType to know which submodel (text encoder, VAE, transformer, tokenizer) of the Z-Image pipeline to resolve and return; with submodel_type None there is nothing to resolve, so it raises Exception. Main-pipeline loading is decomposed into per-submodel loads, each of which must state its type.

Source

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

        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

        # Z-Image prefers bfloat16, but use safe dtype based on target device capabilities.
        target_device = TorchDevice.choose_torch_device()
        dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Pass the desired SubModelType, e.g. _load_model(config, SubModelType.Transformer).
2. Use the ModelManager/ModelLoaderRegistry entry points so submodel types are supplied automatically per submodel load.
3. Note the earlier CheckpointConfigBase check: also ensure the config is not a checkpoint config or you will hit the NotImplementedError first.

Example fix

// before
transformer = loader._load_model(config)

// after
from invokeai.backend.model_manager.taxonomy import SubModelType
transformer = loader._load_model(config, SubModelType.Transformer)

if submodel_type is None:
    raise ValueError("submodel_type is required when loading Z-Image main pipelines")

def has_submodel_type(st: SubModelType | None) -> bool:
    return st is not None

try:
    model = loader._load_model(config, submodel_type)
except Exception as e:
    if "A submodel type must be provided" in str(e):
        raise RuntimeError("Pass SubModelType when loading Z-Image pipelines, or use ModelManager.load_model") from e
    raise

When it happens

Trigger: Calling ZImageLoader._load_model(config) without submodel_type, or a dispatch path that drops the SubModelType when loading Z-Image main pipelines.

Common situations: Direct calls to _load_model in custom scripts; refactors or third-party integrations that assumed a single-file checkpoint loader signature (where submodel_type is optional); generic loader wrappers that pass only the config.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• A submodel type (Tokenizer or TextEncoder) must be provided.
• Expected ModelPatchRaw for LoRA '{lora.lora.key}', got {type
• Unknown model (%s)
• in_channels must be divisible by groups
• out_channels must be divisible by groups

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