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

Loading a main Stable Diffusion pipeline from a diffusers directory requires knowing which component to build (UNet, VAE, text encoder, tokenizer, scheduler); without a submodel_type the loader cannot proceed, so it raises an Exception. Checkpoint (single-file) configs are exempt because they load via a different path.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/stable_diffusion.py:71

@ModelLoaderRegistry.register(base=BaseModelType.StableDiffusion1, type=ModelType.Main, format=ModelFormat.Checkpoint)
@ModelLoaderRegistry.register(base=BaseModelType.StableDiffusion2, type=ModelType.Main, format=ModelFormat.Checkpoint)
@ModelLoaderRegistry.register(base=BaseModelType.StableDiffusionXL, type=ModelType.Main, format=ModelFormat.Checkpoint)
@ModelLoaderRegistry.register(
    base=BaseModelType.StableDiffusionXLRefiner, type=ModelType.Main, format=ModelFormat.Checkpoint
)
class StableDiffusionDiffusersModel(GenericDiffusersLoader):
    """Class to load main models."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if isinstance(config, Checkpoint_Config_Base):
            return self._load_from_singlefile(config, submodel_type)

        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
        try:
            result: AnyModel = load_class.from_pretrained(
                model_path,
                torch_dtype=self._torch_dtype,
                variant=variant,
                local_files_only=True,
            )
        except OSError as e:
            if variant and "no file named" in str(
                e
            ):  # try without the variant, just in case user's preferences changed
                result = load_class.from_pretrained(model_path, torch_dtype=self._torch_dtype, local_files_only=True)

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Pass the desired SubModelType (e.g. SubModelType.UNet, VAE, TextEncoder, Tokenizer, Scheduler) when loading a main diffusers model.
2. If you need the whole pipeline, load via the pipeline-level API rather than the component loader.
3. Confirm the config type: single-file checkpoints don't require submodel_type, diffusers folders do.

Example fix

// before
model = loader.load_model(diffusers_config, submodel_type=None)
// after
model = loader.load_model(diffusers_config, submodel_type=SubModelType.UNet)

from invokeai.backend.model_manager.config import Checkpoint_Config_Base
if not isinstance(config, Checkpoint_Config_Base) and submodel_type is None:
    raise ValueError("submodel_type is required for diffusers main pipelines")

def requires_submodel(config) -> bool:
    return not isinstance(config, Checkpoint_Config_Base)

try:
    model = loader.load_model(config, submodel_type=sub)
except Exception as e:
    if "submodel type must be provided" in str(e):
        logger.error("Pass a SubModelType when loading diffusers main pipelines")
    raise

When it happens

Trigger: Calling the StableDiffusion loader with a diffusers-folder config and submodel_type=None; a caller forgetting to pass the component when loading a main model; code paths that only handle single-file configs.

Common situations: Custom automation/scripts that load 'the model' expecting the whole pipeline; refactors that dropped the submodel argument; confusion between Checkpoint and Diffusers config 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

• Only Tokenizer and TextEncoder submodels are supported. Rece
• A submodel type must be provided when loading onnx pipelines
• Unexpected submodel requested for PiD decoder.
• Unexpected submodel requested for LLaVA OneVision model.
• Unexpected submodel requested for TextLLM model.

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