invoke-ai/InvokeAI · error · Exception

A submodel type must be provided when loading onnx pipelines

Error message

A submodel type must be provided when loading onnx pipelines.

What it means

OnnyxDiffusersModel._load_model requires a SubModelType because ONNX pipelines are loaded piecewise (one onnx_model per subfolder like text_encoder/, unet/, vae/) via get_hf_load_class; with submodel_type=None it cannot pick a load class or subfolder, so it raises Exception. Note the guard 'if not submodel_type is not None' is a double negative that fires exactly when submodel_type is None.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/onnx.py:31

    BaseModelType,
    ModelFormat,
    ModelType,
    SubModelType,
)


@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.ONNX, format=ModelFormat.ONNX)
@ModelLoaderRegistry.register(base=BaseModelType.Any, type=ModelType.ONNX, format=ModelFormat.Olive)
class OnnyxDiffusersModel(GenericDiffusersLoader):
    """Class to load onnx models."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if not submodel_type is not None:
            raise Exception("A submodel type must be provided when loading onnx pipelines.")
        model_path = Path(config.path)
        load_class = self.get_hf_load_class(model_path, submodel_type)
        repo_variant = getattr(config, "repo_variant", None)
        variant = repo_variant.value if repo_variant else None
        model_path = model_path / submodel_type.value
        result: AnyModel = load_class.from_pretrained(
            model_path,
            torch_dtype=self._torch_dtype,
            variant=variant,
            local_files_only=True,
        )
        return result

View on GitHub (pinned to 0b6a024f2f)

Solutions

Always pass a SubModelType (e.g. SubModelType.TextEncoder, UNet, VAE) when loading ONNX/Olive models.
Let the model manager's per-submodel loading machinery supply submodel_type rather than loading the whole pipeline directly.
If you need the entire pipeline, use ONNXPipeline loading at a higher level, not this submodel loader.

Example fix

// before
model = onnx_loader._load_model(cfg)  # Exception: submodel type required
// after
model = onnx_loader._load_model(cfg, SubModelType.UNet)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager.taxonomy import SubModelType

if submodel_type is None:
    raise ValueError("pass an explicit SubModelType when loading ONNX models")
model = onnx_loader._load_model(cfg, submodel_type)

Try / catch

try:
    model = onnx_loader._load_model(cfg, submodel_type)
except Exception as e:
    if "submodel type must be provided" in str(e):
        model = onnx_loader._load_model(cfg, SubModelType.UNet)  # or resolve per pipeline
    else:
        raise

Prevention

Treat ONNX/Olive models as per-submodel loads only; never load them whole.
Never rely on the submodel_type=None default for ONNX records.
Use the model manager's pipeline loading which supplies submodels automatically.

When it happens

Trigger: Calling the ONNX loader with submodel_type=None (the default), e.g. loading an ONNX/Olive model record as a whole instead of per-submodel; custom loader code that omits the submodel argument for ONNX models.

Common situations: Code that loads main models generically without per-submodel dispatch; scripts treating ONNX model folders like single-file checkpoints; direct _load_model calls during testing.

Related errors

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