{"record":{"id":"1f6a2040f78188ca","repo":"invoke-ai/InvokeAI","slug":"only-tokenizer-and-textencoder-submodels-are-suppo-1f6a20","errorCode":null,"errorMessage":"Only Tokenizer and TextEncoder submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}","messagePattern":"Only Tokenizer and TextEncoder submodels are supported\\. Received: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/backend/model_manager/load/model_loaders/z_image.py","lineNumber":793,"sourceCode":"\n        match submodel_type:\n            case SubModelType.Tokenizer:\n                # Use local_files_only=True to prevent network requests for validation\n                # The tokenizer files should already exist locally in the model directory\n                return AutoTokenizer.from_pretrained(tokenizer_path, local_files_only=True)\n            case SubModelType.TextEncoder:\n                # Determine safe dtype based on target device capabilities\n                target_device = TorchDevice.choose_torch_device()\n                model_dtype = TorchDevice.choose_bfloat16_safe_dtype(target_device)\n                # Use local_files_only=True to prevent network requests for validation\n                return Qwen3ForCausalLM.from_pretrained(\n                    text_encoder_path,\n                    torch_dtype=model_dtype,\n                    low_cpu_mem_usage=True,\n                    local_files_only=True,\n                )\n\n        raise ValueError(\n            f\"Only Tokenizer and TextEncoder submodels are supported. Received: {submodel_type.value if submodel_type else 'None'}\"\n        )\n\n\n@ModelLoaderRegistry.register(base=BaseModelType.ZImage, type=ModelType.ControlNet, format=ModelFormat.Checkpoint)\nclass ZImageControlCheckpointModel(ModelLoader):\n    \"\"\"Class to load Z-Image Control adapter models from safetensors checkpoint.\n\n    Z-Image Control models are standalone adapters containing control layers\n    (control_layers, control_all_x_embedder, control_noise_refiner) that can be\n    combined with a base ZImageTransformer2DModel at runtime for spatial conditioning\n    (Canny, HED, Depth, Pose, MLSD).\n    \"\"\"\n\n    def _load_model(\n        self,\n        config: AnyModelConfig,\n        submodel_type: Optional[SubModelType] = None,","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/load/model_loaders/z_image.py#L775-L811","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Load only the Tokenizer or TextEncoder submodel through this loader; let the dedicated Z-Image transformer/VAE loaders handle other submodel types.","Verify the model's config records the correct ModelType/BaseModelType so submodel requests are routed to the right loader class.","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.","Pass an explicit submodel_type (Tokenizer or TextEncoder) if calling the loader programmatically, instead of relying on None."],"exampleFix":"// before\nmodel = loader._load_model(config, submodel_type=None)\n// after\nif submodel_type in (SubModelType.Tokenizer, SubModelType.TextEncoder):\n    model = loader._load_model(config, submodel_type=submodel_type)\nelse:\n    raise ValueError(f\"Use the dedicated Z-Image loader for {submodel_type}\")","handlingStrategy":"validation","validationCode":"ALLOWED = {SubModelType.Tokenizer, SubModelType.TextEncoder}\nif submodel_type not in ALLOWED:\n    raise ValueError(f\"Z-Image checkpoint loader handles only {ALLOWED}, got {submodel_type}\")","typeGuard":"def is_text_submodel(st: SubModelType | None) -> bool:\n    return st in (SubModelType.Tokenizer, SubModelType.TextEncoder)","tryCatchPattern":"try:\n    model = loader._load_model(config, submodel_type=st)\nexcept ValueError as e:\n    if \"Only Tokenizer and TextEncoder\" in str(e):\n        logger.warning(\"Reroute %s to its dedicated loader\", st)\n    else:\n        raise","preventionTips":["Only request Tokenizer/TextEncoder submodels from Z-Image checkpoint models.","Keep each model's ModelType accurate so dispatch reaches the right loader.","Never pass submodel_type=None to this loader.","Cover all SubModelType branches in custom pipeline dispatch tests."],"tags":["invokeai","z-image","model-loader","unsupported-submodel"],"backgroundTag":"unsupported-submodel-type","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}