invoke-ai/InvokeAI · error · ValueError

Only Tokenizer and TextEncoder submodels are supported. Rece

Error message

Only Tokenizer and TextEncoder submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}

What it means

InvokeAI's Z-Image checkpoint loader only knows how to extract Tokenizer and TextEncoder submodels from a Z-Image main-checkpoint file. If the model manager asks this loader for any other submodel type (or None), it cannot slice that component out of the checkpoint, so it raises this ValueError to signal the loader/submodel combination is unsupported.

Source

Thrown at invokeai/backend/model_manager/load/model_loaders/z_image.py:793

        match submodel_type:
            case SubModelType.Tokenizer:
                # Use local_files_only=True to prevent network requests for validation
                # The tokenizer files should already exist locally in the model directory
                return AutoTokenizer.from_pretrained(tokenizer_path, local_files_only=True)
            case SubModelType.TextEncoder:
                # Determine safe dtype based on target device capabilities
                target_device = TorchDevice.choose_torch_device()
                model_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)
                # Use local_files_only=True to prevent network requests for validation
                return Qwen3ForCausalLM.from_pretrained(
                    text_encoder_path,
                    torch_dtype=model_dtype,
                    low_cpu_mem_usage=True,
                    local_files_only=True,
                )

        raise ValueError(
            f"Only Tokenizer and TextEncoder submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}"
        )


@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint)
class ZImageControlCheckpointModel(ModelLoader):
    """Class to load Z-Image Control adapter models from safetensors checkpoint.

    Z-Image Control models are standalone adapters containing control layers
    (control_layers, control_all_x_embedder, control_noise_refiner) that can be
    combined with a base ZImageTransformer2DModel at runtime for spatial conditioning
    (Canny, HED, Depth, Pose, MLSD).
    """

    def _load_model(
        self,
        config: AnyModelConfig,
        submodel_type: Optional[SubModelType] = None,

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Load only the Tokenizer or TextEncoder submodel through this loader; let the dedicated Z-Image transformer/VAE loaders handle other submodel types.
  2. Verify the model's config records the correct ModelType/BaseModelType so submodel requests are routed to the right loader class.
  3. If you need a different submodel from a Z-Image checkpoint, add a case in the match/if-chain in _load_model that loads it explicitly.
  4. Pass an explicit submodel_type (Tokenizer or TextEncoder) if calling the loader programmatically, instead of relying on None.

Example fix

// before
model = loader._load_model(config, submodel_type=None)
// after
if submodel_type in (SubModelType.Tokenizer, SubModelType.TextEncoder):
    model = loader._load_model(config, submodel_type=submodel_type)
else:
    raise ValueError(f"Use the dedicated Z-Image loader for {submodel_type}")
Defensive patterns

Strategy: validation

Validate before calling

ALLOWED = {SubModelType.Tokenizer, SubModelType.TextEncoder}
if submodel_type not in ALLOWED:
    raise ValueError(f"Z-Image checkpoint loader handles only {ALLOWED}, got {submodel_type}")

Type guard

def is_text_submodel(st: SubModelType | None) -> bool:
    return st in (SubModelType.Tokenizer, SubModelType.TextEncoder)

Try / catch

try:
    model = loader._load_model(config, submodel_type=st)
except ValueError as e:
    if "Only Tokenizer and TextEncoder" in str(e):
        logger.warning("Reroute %s to its dedicated loader", st)
    else:
        raise

Prevention

When it happens

Trigger: Registering/invoking ZImageCheckpointModel._load_model with submodel_type set to anything other than SubModelType.Tokenizer or SubModelType.TextEncoder (e.g. Vae, Transformer, Scheduler), or calling it with submodel_type=None while loading a Z-Image checkpoint-format model.

Common situations: A model-manager refactor or custom pipeline requests submodels from the wrong loader; a user places a Z-Image diffusers-style model in checkpoint format so submodel dispatch reaches this loader for components it does not own; a custom script iterates all SubModelType values against every loader.

Related errors

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