{"record":{"id":"116f1e5cbdde6bb6","repo":"invoke-ai/InvokeAI","slug":"only-textencoder-and-tokenizer-submodels-are-suppo","errorCode":null,"errorMessage":"Only TextEncoder and Tokenizer submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}","messagePattern":"Only TextEncoder and Tokenizer submodels are supported\\. Received: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":922,"sourceCode":"class Qwen3EncoderCheckpointLoader(ModelLoader):\n    \"\"\"Class to load single-file Qwen3 Encoder models for Z-Image (safetensors format).\"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,\n    ) -> AnyModel:\n        if not isinstance(config, Qwen3Encoder_Checkpoint_Config):\n            raise ValueError(\"Only Qwen3Encoder_Checkpoint_Config models are supported here.\")\n\n        match submodel_type:\n            case SubModelType.TextEncoder:\n                return self._load_from_singlefile(config)\n            case SubModelType.Tokenizer:\n                # Single-file checkpoints ship no tokenizer files; use the vendored copy.\n                return self._load_bundled_tokenizer()\n\n        raise ValueError(\n            f\"Only TextEncoder and Tokenizer submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}\"\n        )\n\n    def _load_bundled_tokenizer(self) -> AnyModel:\n        \"\"\"Load the Qwen3 tokenizer from the vendored, bundled copy.\n\n        Single-file / GGUF checkpoints do not ship tokenizer files. The Qwen3 BPE\n        tokenizer is identical across the 0.6B / 4B / 8B variants, so we load the\n        self-contained copy vendored in the package — fully offline, no HuggingFace\n        download required.\n        \"\"\"\n        return load_bundled_qwen3_tokenizer()\n\n    def _load_from_singlefile(\n        self,\n        config: AnyModelConfig,\n    ) -> AnyModel:\n        from safetensors.torch import load_file","sourceCodeStart":904,"sourceCodeEnd":940,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L904-L940","documentation":"This loader handles exactly two submodel types for the Qwen3 single-file text encoder: TextEncoder (loads weights from the checkpoint) and Tokenizer (loads the vendored bundled tokenizer). Any other submodel request — or a None — has no handling branch, so the loader raises this ValueError to report the unsupported combination.","triggerScenarios":"Calling ZImageQwen3EncoderCheckpointModel._load_model with submodel_type values like Vae, Transformer, Scheduler, or None; model-manager dispatch mistakenly routes non-text submodels of a Z-Image model to the Qwen3 encoder loader.","commonSituations":"A pipeline component resolver iterates all submodel types per model; a custom workflow requests the VAE through the text-encoder loader; mis-set ModelType on the model record causes wrong loader selection.","solutions":["Request only TextEncoder or Tokenizer from this loader; obtain VAE/transformer from their own registered loaders.","Pass an explicit valid SubModelType if calling the loader directly rather than None.","Verify the model's ModelType is TextEncoder so only the correct submodels are requested.","Add an explicit case in the match statement if a new submodel must be supported by this loader."],"exampleFix":"// before\nmodel = loader._load_model(config, submodel_type=SubModelType.Vae)\n// after\nassert submodel_type in (SubModelType.TextEncoder, SubModelType.Tokenizer)\nmodel = loader._load_model(config, submodel_type=submodel_type)","handlingStrategy":"validation","validationCode":"if submodel_type not in (SubModelType.TextEncoder, SubModelType.Tokenizer):\n    raise ValueError(f\"Qwen3 checkpoint loader supports TextEncoder/Tokenizer only, got {submodel_type}\")","typeGuard":"def is_qwen3_supported_submodel(st: SubModelType | None) -> bool:\n    return st in (SubModelType.TextEncoder, SubModelType.Tokenizer)","tryCatchPattern":"try:\n    model = loader._load_model(config, submodel_type=st)\nexcept ValueError as e:\n    if \"Only TextEncoder and Tokenizer\" in str(e):\n        model = other_loader_for(st)._load_model(config, submodel_type=st)\n    else:\n        raise","preventionTips":["Fetch VAE/transformer components from their own registered loaders.","Always pass an explicit SubModelType when calling loaders directly.","Keep the model record's ModelType=TextEncoder so dispatch stays correct.","Route errors to the correct loader rather than retrying the same one."],"tags":["invokeai","z-image","qwen3","unsupported-submodel"],"backgroundTag":"unsupported-submodel-type","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}