{"record":{"id":"eb6f3a6c5222a477","repo":"invoke-ai/InvokeAI","slug":"model-is-a-wan-family-vae-not-a-standard-vae","errorCode":null,"errorMessage":"model is a Wan-family VAE, not a standard VAE","messagePattern":"model is a Wan-family VAE, not a standard VAE","errorType":"validation","errorClass":"NotAMatchError","httpStatus":null,"severity":"warning","filePath":"invokeai/backend/model_manager/configs/vae.py","lineNumber":153,"sourceCode":"    def _validate_looks_like_vae(cls, mod: ModelOnDisk) -> None:\n        state_dict = mod.load_state_dict()\n        if not state_dict_has_any_keys_starting_with(\n            state_dict,\n            {\n                \"encoder.conv_in\",\n                \"decoder.conv_in\",\n            },\n        ):\n            raise NotAMatchError(\"model does not match Checkpoint VAE heuristics\")\n\n        # Exclude FLUX.2 VAEs - they have their own config class\n        if _is_flux2_vae(state_dict):\n            raise NotAMatchError(\"model is a FLUX.2 VAE, not a standard VAE\")\n\n        # Exclude Qwen Image / Wan VAEs - they share the AutoencoderKLWan\n        # architecture and each has its own config class.\n        if _is_qwen_image_vae(state_dict) or _wan_vae_z_dim(state_dict) is not None:\n            raise NotAMatchError(\"model is a Wan-family VAE, not a standard VAE\")\n\n    @classmethod\n    def _get_base_or_raise(cls, mod: ModelOnDisk) -> BaseModelType:\n        # First, try to identify by latent space dimensions (most reliable)\n        state_dict = mod.load_state_dict()\n        decoder_conv_in_key = \"decoder.conv_in.weight\"\n        if decoder_conv_in_key in state_dict:\n            latent_channels = state_dict[decoder_conv_in_key].shape[1]\n            if latent_channels == 16:\n                # Flux1 VAE has 16-dimensional latent space\n                return BaseModelType.Flux\n            elif latent_channels == 4:\n                # SD/SDXL VAE has 4-dimensional latent space\n                # Try to distinguish SD1/SD2/SDXL by name, fallback to SD1\n                for regexp, base in REGEX_TO_BASE.items():\n                    if re.search(regexp, mod.path.name, re.IGNORECASE):\n                        return base\n                # Default to SD1 if we can't determine from name","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/backend/model_manager/configs/vae.py#L135-L171","documentation":"InvokeAI's VAE model probe (_validate_looks_like_vae) checks a candidate VAE's state_dict to make sure it is a standard AutoencoderKL. When the weights match a FLUX.2 VAE, a Qwen Image VAE, or any Wan-family VAE (AutoencoderKLWan architecture, detected via _wan_vae_z_dim), the probe raises NotAMatchError because each of those architectures has its own dedicated config class and must not be registered as a generic VAE.","triggerScenarios":"Calling VAE.from_model_on_disk (directly or via model import/scan) on a directory or checkpoint whose state_dict matches _is_qwen_image_vae or returns a non-None z-dim from _wan_vae_z_dim.","commonSituations":"User downloads a Wan 2.1/2.2 VAE or Qwen Image VAE and drops it into the VAE folder, expecting the generic VAE importer to accept it; bulk re-scanning a model library after adding new-community Wan-family checkpoints.","solutions":["Let InvokeAI scan the model normally; it will be registered under the correct Qwen/Wan config class, not as a standard VAE.","Verify the file really is a VAE and not mislabeled; if you intended a standard SD VAE, re-download from the correct source.","If support for this VAE is missing in your InvokeAI version, upgrade to a version that registers the specific Wan/Qwen VAE config class."],"exampleFix":"// before: forcing a Wan VAE through the generic VAE probe\nconfig = VAE.from_model_on_disk(wan_vae_dir, base=BaseModelType.Any)\n// after: let the installer pick the right config family, or check first\nfrom invokeai.backend.model_manager.configs.vae import _wan_vae_z_dim\nif _wan_vae_z_disk_dict(wan_vae_dir) is not None:\n    raise ValueError(\"Wan-family VAE; use the Wan model installer instead of the generic VAE importer\")","handlingStrategy":"validation","validationCode":"from invokeai.backend.model_manager.configs.vae import _wan_vae_z_dim, _is_qwen_image_vae\nsd = model_on_disk.load_state_dict()\nif _is_qwen_image_vae(sd) or _wan_vae_z_dim(sd) is not None:\n    print(\"Wan/Qwen-family VAE: use its dedicated config class, not the generic VAE importer\")","typeGuard":"def is_standard_vae(state_dict) -> bool:\n    return not (_is_flux2_vae(state_dict) or _is_qwen_image_vae(state_dict) or _wan_vae_z_dim(state_dict) is not None)","tryCatchPattern":"from invokeai.backend.model_manager.configs.base import NotAMatchError\ntry:\n    config = VAE.from_model_on_disk(model_path, base=BaseModelType.Any)\nexcept NotAMatchError:\n    config = scan_model(model_path)  # fall back to generic identification","preventionTips":["Import models via the Model Manager scan rather than forcing a specific config class","Keep Wan/Qwen/FLUX.2 VAEs in their expected folders and let identification classify them","When a probe reports NotAMatchError, read the message — it names the actual architecture"],"tags":["model-import","vae","model-detection"],"backgroundTag":"model-architecture-mismatch","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}