invoke-ai/InvokeAI · error · ValueError

Only the Transformer submodel is available from a single-fil

Error message

Only the Transformer submodel is available from a single-file Wan checkpoint. Pair with a standalone Wan VAE and Wan T5 encoder for the other components.

What it means

Like the GGUF loader, the regular single-file Wan checkpoint contains only transformer weights; VAE and T5 text encoder must come from standalone models. Any submodel_type other than Transformer is rejected with this ValueError.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/wan.py:487

    ``model.diffusion_model.`` key prefix, the native upstream key layout as well
    as the diffusers one, ComfyUI ``fp8_scaled`` weights (dequantized to the
    compute dtype at load time), and plain ``float8_e4m3fn`` weights with no
    scales (cast the same way as any other non-bf16 dtype).

    Like the GGUF loader, one file is one expert; A14B pairing happens at the
    WanModelLoaderInvocation layer.
    """

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,
    ) -> AnyModel:
        if not isinstance(config, Main_Checkpoint_Wan_Config):
            raise TypeError(f"Expected Main_Checkpoint_Wan_Config, got {type(config).__name__}.")

        if submodel_type != SubModelType.Transformer:
            raise ValueError(
                "Only the Transformer submodel is available from a single-file Wan checkpoint. "
                "Pair with a standalone Wan VAE and Wan T5 encoder for the other components."
            )

        return self._load_from_singlefile(config)

    def _load_from_singlefile(self, config: Main_Checkpoint_Wan_Config) -> AnyModel:
        import accelerate
        from diffusers import WanTransformer3DModel
        from safetensors.torch import load_file

        from invokeai.backend.util.logging import InvokeAILogger

        logger = InvokeAILogger.get_logger(self.__class__.__name__)

        model_path = Path(config.path)
        target_device = TorchDevice.choose_torch_device()
        model_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Request only SubModelType.Transformer from the single-file Wan checkpoint record.
Register standalone Wan VAE and T5 encoder models and use them for the other components.
Use a full Wan diffusers-pipeline model if you want VAE/text-encoder included.

Example fix

// before
t5 = manager.load_model(wan_ckpt_config, submodel_type=SubModelType.TextEncoder)

// after
transformer = manager.load_model(wan_ckpt_config, submodel_type=SubModelType.Transformer)
t5 = manager.load_model(wan_t5_config, submodel_type=SubModelType.TextEncoder)

Defensive patterns

Strategy: validation

Validate before calling

from invokeai.backend.model_manager import SubModelType

def validate_ckpt_submodel(submodel_type):
    if submodel_type != SubModelType.Transformer:
        raise ValueError("Single-file Wan checkpoints provide only the Transformer; pair with standalone VAE/T5 models")

Try / catch

try:
    model = manager.load_model(wan_ckpt_config, submodel_type)
except ValueError as e:
    if 'Only the Transformer submodel' in str(e):
        model = manager.load_model(wan_ckpt_config, submodel_type=SubModelType.Transformer)
    else:
        raise

Prevention

Load only the Transformer submodel from single-file Wan checkpoints.
Register separate Wan VAE and T5 encoder records for the other components.
Use full Wan diffusers-pipeline models when you need bundled VAE/text-encoder.
Avoid blanket code that requests every SubModelType from every model record.

When it happens

Trigger: Requesting SubModelType.VAE, SubModelType.TextEncoder, or None while loading a Main_Checkpoint_Wan_Config model record; automation iterating all submodels against the single-file checkpoint.

Common situations: Assuming a .safetensors Wan checkpoint is a full pipeline; config listing the checkpoint as the source for VAE/text-encoder submodels; scripts copied from diffusers-pipeline loading flows.

Related errors

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