invoke-ai/InvokeAI · error · Exception

A submodel type must be provided when loading Ideogram 4 mai

Error message

A submodel type must be provided when loading Ideogram 4 main pipelines.

What it means

Main pipeline loaders load individual components (transformer, text encoder, tokenizer, VAE), so the caller must say which submodel to load via submodel_type. A None value gives the loader nothing to dispatch on, so it raises. Unlike the config-type check, this one uses a bare Exception to signal a caller contract violation.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/ideogram4.py:85

        raise RuntimeError(
            f"{context}: {len(meta)} parameter(s) remain on the meta device after loading "
            f"(missing or mismatched weights): {meta[:10]}"
        )


@ModelLoaderRegistry.register(base=BaseModelType.Ideogram4, type=ModelType.Main, format=ModelFormat.Diffusers)
class Ideogram4DiffusersModel(ModelLoader):
    """Loads Ideogram 4 main models (nf4 / fp8) bundled in diffusers layout."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if not isinstance(config, Main_Diffusers_Ideogram4_Config):
            raise ValueError(f"Expected Main_Diffusers_Ideogram4_Config, got {type(config).__name__}.")
        if submodel_type is None:
            raise Exception("A submodel type must be provided when loading Ideogram 4 main pipelines.")

        model_path = Path(config.path)

        match submodel_type:
            case SubModelType.Transformer:
                return self._load_transformer_pair(model_path)
            case SubModelType.TextEncoder:
                return self._load_text_encoder(model_path)
            case SubModelType.Tokenizer:
                from transformers import AutoTokenizer

                return AutoTokenizer.from_pretrained(model_path / "tokenizer", local_files_only=True)
            case SubModelType.VAE:
                return self._load_vae(model_path)

        raise ValueError(
            f"Unsupported submodel for Ideogram 4: {submodel_type.value if submodel_type else 'None'}. "
            "Supported: Transformer, TextEncoder, Tokenizer, VAE."

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass an explicit SubModelType (Transformer, TextEncoder, Tokenizer, or VAE) when invoking the loader.
If the whole pipeline is wanted, iterate over the supported submodel types and load each separately.
Fix the calling layer so submodel_type is always populated for Main/Diffusers models.

Example fix

// before
model = loader._load_model(cfg, None)
// after
model = loader._load_model(cfg, SubModelType.Transformer)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager import SubModelType
if submodel_type is None:
    raise ValueError("submodel_type is required for main diffusers pipelines")

Type guard

def submodel_provided(submodel_type) -> bool:
    from invokeai.backend.model_manager import SubModelType
    return isinstance(submodel_type, SubModelType)

Try / catch

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

Prevention

Always pass an explicit SubModelType for Main-model loads.
Default submodel parameters in calling code to the primary component (e.g. Transformer).
Unit-test loading helpers with each model family to catch None-passing paths.

When it happens

Trigger: Calling _load_model for an Ideogram 4 main pipeline with submodel_type=None (e.g. a caller that treats main pipelines as monolithic single-file loads).

Common situations: Generic loading code that passes submodel_type=None for single-file checkpoint loaders being reused against a diffusers-format main pipeline.

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