invoke-ai/InvokeAI · error · ValueError

A submodel type (Tokenizer or TextEncoder) must be provided.

Error message

A submodel type (Tokenizer or TextEncoder) must be provided.

What it means

WanModelLoader._load_model loads submodels (tokenizers, text encoders) of a Wan pipeline by delegating per-submodel, and the submodel_type argument tells it which piece to fetch. The library raises ValueError when submodel_type is None because there is no sensible default: a loader that receives no submodel type cannot know whether to return the Tokenizer or the TextEncoder. This indicates a loader orchestration bug or a caller invoking _load_model directly without the required argument.

Source

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

@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.WanT5Encoder, format=ModelFormat.WanT5Encoder)
class WanT5EncoderLoader(ModelLoader):
    """Loader for the standalone Wan UMT5-XXL encoder.

    Accepts two on-disk layouts:
    1. Parent dir with ``text_encoder/`` (and typically ``tokenizer/``) subdirs —
       what ``Wan-AI/Wan2.2-T2V-A14B::text_encoder+tokenizer`` produces.
    2. A flat ``text_encoder/`` folder with ``config.json`` declaring
       ``model_type: umt5`` directly at the root. In this case the tokenizer
       is loaded from the same folder via ``AutoTokenizer.from_pretrained``.
    """

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if submodel_type is None:
            raise ValueError("A submodel type (Tokenizer or TextEncoder) must be provided.")

        root = Path(config.path)
        nested_text_encoder = root / "text_encoder"
        nested_tokenizer = root / "tokenizer"

        if submodel_type == SubModelType.TextEncoder:
            from transformers import UMT5EncoderModel

            target = nested_text_encoder if nested_text_encoder.exists() else root
            return UMT5EncoderModel.from_pretrained(
                str(target),
                torch_dtype=torch.bfloat16,
                local_files_only=True,
            )
        if submodel_type == SubModelType.Tokenizer:
            from transformers import AutoTokenizer

            # Prefer a sibling tokenizer/ directory; fall back to the encoder dir

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Pass an explicit submodel_type, e.g. loader._load_model(config, SubModelType.Tokenizer) or SubModelType.TextEncoder.
2. Load the main Wan pipeline through the standard ModelManager/ModelLoaderRegistry API instead of calling _load_model directly so submodels are dispatched correctly.
3. If you maintain the loader, raise earlier with a clearer message or default the dispatch in the caller that enumerates submodels.

Example fix

// before
model = loader._load_model(config)

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

if submodel_type is None:
    raise ValueError("submodel_type is required for Wan submodel loading; pass SubModelType.Tokenizer or SubModelType.TextEncoder")

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

try:
    model = loader._load_model(config, submodel_type)
except ValueError as e:
    if "submodel type" in str(e):
        model = loader._load_model(config, SubModelType.TextEncoder)
    else:
        raise

When it happens

Trigger: Calling WanModelLoader._load_model(config) with submodel_type omitted/None, or a ModelLoaderRegistry/pipeline-load path that fails to pass SubModelType when dispatching submodel loads for Wan models.

Common situations: Custom loader code calling _load_model directly for the main model; a refactor that dropped the submodel_type kwarg; a generic loading helper written for single-file models reused on diffusers-style Wan folders where submodels are loaded separately.

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

• Unsupported submodel type for WanT5Encoder: {submodel_type.v
• A submodel type must be provided when loading main pipelines
• Invalid mode selected
• Unexpected control_input type: ${type(control_input)}
• Unexpected T2I-Adapter base model type: '${t2i_adapter_model

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