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

The Qwen Image main-pipeline model loader requires a submodel_type (e.g. transformer, vae, tokenizer) whenever the model is a main/diffusers pipeline so it can pick the correct subfolder and HF load class. If _load_model is invoked with submodel_type=None for a main pipeline (non-checkpoint config path), it raises this bare Exception. It signals a dispatch bug or a model registered as a pipeline without a submodel context.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/qwen_image.py:145

        model_config["zero_cond_t"] = True

    return model_config


@ModelLoaderRegistry.register(base=BaseModelType.QwenImage, type=ModelType.Main, format=ModelFormat.Diffusers)
class QwenImageDiffusersModel(GenericDiffusersLoader):
    """Class to load Qwen Image Edit main models."""

    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 Qwen Image Edit models.")

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

        model_path = Path(config.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
        model_path = model_path / submodel_type.value

        # We force bfloat16 for Qwen Image Edit models.
        # Use `dtype` (newer) with fallback to `torch_dtype` (older diffusers).
        dtype_kwarg = {"dtype": torch.bfloat16}
        try:
            result: AnyModel = load_class.from_pretrained(
                model_path,
                **dtype_kwarg,
                variant=variant,
                local_files_only=True,
            )
        except TypeError:

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass the SubModelType you intend to load (e.g. SubModelType.Transformer) as the second argument to _load_model.
Load models through the ModelManager/model manager service so submodel_type is resolved automatically from the pipeline.
If the model is actually a single-file checkpoint, ensure its config is CheckpointConfigBase and use the single-file loader instead of the diffusers main loader.

Example fix

// before
model = loader._load_model(config, None)
// after
from invokeai.backend.model_manager import SubModelType
model = loader._load_model(config, SubModelType.Transformer)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager import SubModelType
if submodel_type is None:
    raise ValueError("Provide a SubModelType (e.g. SubModelType.Transformer) when loading a Qwen Image main pipeline.")
loader._load_model(config, submodel_type)

Type guard

def has_submodel(sub: SubModelType | None) -> bool:
    return sub is not None

Try / catch

try:
    model = loader._load_model(config, submodel_type)
except Exception as e:
    if "submodel type must be provided" in str(e):
        model = loader._load_model(config, SubModelType.Transformer)
    else:
        raise

Prevention

Always load models via ModelManager so submodel_type is resolved automatically
Never call _load_model directly with None for main pipelines
Assert submodel_type is not None before loader calls in scripts

When it happens

Trigger: Calling QwenImageDiffusersModelLoader._load_model(config, None) where config is NOT Checkpoint_Config_Base (the earlier isinstance raises NotImplementedError first for checkpoint configs), i.e. loading a Qwen Image main pipeline without specifying which submodel to load.

Common situations: Directly invoking the loader outside the normal ModelManager pipeline; a registry entry pointing a pipeline at this loader without submodel resolution; custom code that iterates loader APIs and forgets the submodel argument.

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

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