invoke-ai/InvokeAI · error · Exception

A submodel type must be provided when loading Wan main pipel

Error message

A submodel type must be provided when loading Wan main pipelines.

What it means

Wan main pipelines are composite models; this loader needs to know which component (transformer, VAE, text encoder) to build, passed via submodel_type. If submodel_type is None, a plain Exception is raised because no component can be selected.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/wan.py:67

    """Loader for Wan 2.2 diffusers-format models (T2V-A14B and TI2V-5B).

    Forces bfloat16 for the transformer and VAE — fp16 is unstable on Wan VAE
    (same issue affects the Flux VAE). Resolves the appropriate Hugging Face
    class for each submodel via the parent loader's ``get_hf_load_class``.
    """

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if isinstance(config, Checkpoint_Config_Base):
            # Defensive: the registry keys on format, so single-file configs are
            # routed to WanGGUFCheckpointModel / WanCheckpointModel, not here.
            raise TypeError(f"{type(config).__name__} is a single-file config; it does not belong to this loader.")

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

        if submodel_type is SubModelType.VAE:
            from invokeai.backend.wan.rocm_causal_conv3d import patch_wan_causal_conv3d_for_rocm

            patch_wan_causal_conv3d_for_rocm()

        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

        def _load_with_variant_fallback(dtype_kwarg: dict[str, torch.dtype]) -> AnyModel:
            # Some Wan repos ship without a fp16 variant suffix on every submodel.
            # If the requested variant isn't on disk, fall back to the default weights.
            try:
                return load_class.from_pretrained(
                    model_path,

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass an explicit submodel_type (SubModelType.Transformer, SubModelType.VAE, SubModelType.TextEncoder) when loading Wan main pipelines.
Use the normal model-manager load path, which iterates submodels and always supplies submodel_type.
If you only need the transformer, register a single-file Wan checkpoint config instead so the checkpoint loaders apply.

Example fix

// before
model = loader.load_model(config, submodel_type=None)

// after
from invokeai.backend.model_manager import SubModelType
model = loader.load_model(config, submodel_type=SubModelType.Transformer)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager import SubModelType

def validate_wan_load(config, submodel_type):
    assert submodel_type is not None, "Wan main pipelines require an explicit submodel_type"
    assert submodel_type in (SubModelType.Transformer, SubModelType.VAE, SubModelType.TextEncoder)

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, submodel_type=SubModelType.Transformer)
    else:
        raise

Prevention

Never pass submodel_type=None when loading composite (main pipeline) models.
Use the model manager's high-level load API rather than instantiating loaders directly.
Add asserts in automation scripts that submodel_type is set before pipeline loads.

When it happens

Trigger: Loading a Wan pipeline config without specifying SubModelType (e.g., calling _load_model with submodel_type=None), typically when the model manager was asked for the whole pipeline in a context that should request a specific submodel.

Common situations: Custom automation/scripts that call the loader API directly; older integration code written before Wan main-pipeline loading required submodel selection; copy-pasted loader calls from single-component model types.

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/62ff0c09aa6b2ccb. Report an issue: GitHub.