invoke-ai/InvokeAI · error · ValueError

Only Transformer submodels are supported for checkpoint form

Error message

Only Transformer submodels are supported for checkpoint format. Received: {submodel_type}

What it means

SDNQ FLUX checkpoints in single-file format only contain transformer weights, so the loader supports SubModelType.Transformer exclusively for Main_SDNQ_FLUX_Config. Requesting any other submodel (VAE, tokenizer, text encoder) from this checkpoint raises ValueError listing the received submodel type.

Source

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

@ModelLoaderRegistry.register(base=BaseModelType.Flux, type=ModelType.Main, format=ModelFormat.SDNQQuantized)
class FluxSDNQDiffusersModel(ModelLoader):
    """Class to load SDNQ-quantized Flux models in diffusers format."""

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        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)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Load VAE/tokenizers/text encoders from the separate companion components registered alongside the SDNQ checkpoint, not from the checkpoint itself.
Pass SubModelType.Transformer when loading from Main_SDNQ_FLUX_Config.
Re-import the model so all auxiliary components (VAE, text encoders) are registered as their own models.

Example fix

// before
vae = loader.load_model(sdnq_config, SubModelType.Vae)  # raises
// after
transformer = loader.load_model(sdnq_config, SubModelType.Transformer)
vae = loader.load_model(separate_vae_config, SubModelType.Vae)

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(config, Main_SDNQ_FLUX_Config) and submodel_type != SubModelType.Transformer:
    raise RuntimeError("SDNQ single-file checkpoints only provide the transformer; load other components separately")

Type guard

def sdnq_singlefile_supports(config, submodel_type) -> bool:
    return not isinstance(config, Main_SDNQ_FLUX_Config) or submodel_type == SubModelType.Transformer

Try / catch

try:
    model = loader.load_model(config, submodel_type)
except ValueError as e:
    if "Only Transformer submodels" in str(e):
        raise RuntimeError("Fetch VAE/text encoders from their companion models, not the SDNQ checkpoint") from e
    raise

Prevention

Register VAE and text encoders as standalone models alongside SDNQ checkpoints
Remember single-file formats only bundle transformer weights
Check config class before deciding where to load each submodel from

When it happens

Trigger: Loading submodels of an SDNQ single-file FLUX main model: e.g. pipeline assembly requesting SubModelType.Vae or TextEncoder from Main_SDNQ_FLUX_Config instead of the transformer.

Common situations: A diffusers-style folder layout missing sibling components, so the pipeline tries to pull every component from the single-file checkpoint; custom orchestration code calling load_model with the wrong submodel_type.

Related errors

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