invoke-ai/InvokeAI · error · ValueError

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

When loading an SDNQ diffusers FLUX main pipeline, the caller must say which component (submodel) to load. A None submodel_type is ambiguous for a multi-component pipeline, so _load_model raises ValueError demanding a submodel type.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/flux.py:1595

        logger.debug(
            "[SDNQ] FluxSDNQDiffusersModel._load_model called with config=%s, submodel=%s",
            type(config).__name__,
            submodel_type,
        )
        # Handle single-file SDNQ checkpoint (Main_SDNQ_FLUX_Config)
        if isinstance(config, Main_SDNQ_FLUX_Config):
            if submodel_type == SubModelType.Transformer:
                return self._load_sdnq_transformer_checkpoint(config)
            raise ValueError(
                f"Only Transformer submodels are supported for checkpoint format. Received: {submodel_type}"
            )

        # Handle diffusers-format SDNQ model (Main_SDNQ_Diffusers_FLUX_Config)
        if not isinstance(config, Main_SDNQ_Diffusers_FLUX_Config):
            raise ValueError(f"Expected Main_SDNQ_Diffusers_FLUX_Config, got {type(config).__name__}")

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

        # Prefer the path discovery actually found. `model_index.json` names its components with
        # arbitrary keys, and identification records the key it saw — but reconstructing
        # `model_path / submodel_type.value` here assumes the key always equals the slot name. A
        # pipeline whose index calls its CLIP encoder something else is then discovered fine and
        # loaded from a folder that does not exist. Fall back to the conventional name when a config
        # predates submodel discovery.
        model_path = Path(config.path)
        submodel_path = resolve_submodel_path(config, submodel_type, model_path / submodel_type.value)

        # These branches build their modules by hand (`init_empty_weights` + `load_state_dict`)
        # rather than through `from_pretrained`, so they arrive in training mode — `put_in_eval_mode`
        # in `load_default._load_and_cache` is what puts every loaded model into inference mode.
        match submodel_type:
            case SubModelType.Transformer:
                return self._load_sdnq_transformer(submodel_path, config)
            case SubModelType.TextEncoder:
                return self._load_text_encoder(submodel_path)

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Pass an explicit SubModelType (Transformer, VAE, Tokenizer, Tokenizer2, TextEncoder, TextEncoder2) when loading a diffusers main model.
  2. For full-pipeline loading, iterate over the pipeline's components and load each with its own submodel type.
  3. Guard calls so submodel_type defaults to SubModelType.Transformer when omitted.

Example fix

// before
model = loader.load_model(sdnq_diffusers_config, None)
// after
sub = submodel_type or SubModelType.Transformer
model = loader.load_model(sdnq_diffusers_config, sub)
Defensive patterns

Strategy: validation

Validate before calling

if submodel_type is None:
    raise ValueError("Pass an explicit SubModelType (e.g. SubModelType.Transformer) when loading SDNQ diffusers pipelines")

Type guard

def has_submodel(submodel_type: Optional[SubModelType]) -> bool:
    return submodel_type is not None

Try / catch

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

Prevention

When it happens

Trigger: Calling the SDNQ diffusers loader's _load_model (or load_model through the registry) with submodel_type=None for a Main_SDNQ_Diffusers_FLUX_Config.

Common situations: Scripts that load main models without specifying a submodel, which works for checkpoint formats but not diffusers pipelines; default arguments left unset in custom orchestration code.

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