Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-HunyuanImage3 > Load HunyuanImage-3.0 VAE

ComfyUI Node: Load HunyuanImage-3.0 VAE

Class Name

HunyuanImage3VAELoader

Category
hunyuan_image_3
Author
PedroMarinhoDev (Account age: 43days)
Extension
ComfyUI-HunyuanImage3
Latest Updated
2026-11-03
Github Stars
0.04K

How to Install ComfyUI-HunyuanImage3

Install this extension via the ComfyUI Manager by searching for ComfyUI-HunyuanImage3
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-HunyuanImage3 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

Load HunyuanImage-3.0 VAE Description

Loads the correct HunyuanImage-3.0 VAE for image-latent conversion and memory management.

Load HunyuanImage-3.0 VAE:

HunyuanImage3VAELoader, displayed as “Load HunyuanImage-3.0 VAE,” loads the specialized image autoencoder used by HunyuanImage-3.0. A VAE translates between visible images and the compressed image representation, called a latent, that an image-generation model works with. This node explicitly builds the HunyuanImage-3.0 VAE architecture rather than relying on automatic architecture detection, which can confuse this checkpoint with a different Hunyuan Video VAE because their weight files share similar identifying features. That mismatch can produce washed-out images even when the weights appear to load successfully. The node retains ComfyUI’s standard device, precision, and model-management support while replacing the architecture and supplying memory estimates tailored to it. Its main purpose is to provide the correct image conversion for HunyuanImage-3.0 workflows while helping ComfyUI make better memory-management decisions.

Load HunyuanImage-3.0 VAE Input Parameters:

vae_name

A required COMBO selection identifying the VAE weight file to load. Its options are populated dynamically from ComfyUI’s registered vae model locations, so the available filenames depend on your installation; the list is not restricted to compatible HunyuanImage-3.0 files. The tooltip identifies hunyuan_image_3_vae_fp16 and hunyuan_image_3_vae_fp32 as the intended choices and states that one VAE serves all three checkpoints supported by the package. Choose the appropriate HunyuanImage-3.0 VAE rather than an unrelated model, even if another VAE appears in the dropdown. This selection determines which saved weights are loaded into the fixed HunyuanImage-3.0 architecture; incompatible weights can cause loading errors or unusable results. No explicit default is specified in the schema, and numerical minimum and maximum values do not apply. This parameter selects a file, not a runtime precision setting: ComfyUI resolves the working precision separately, and the node supports float16, bfloat16, and float32 operation.

Load HunyuanImage-3.0 VAE Output Parameters:

VAE

A standard ComfyUI VAE object containing the specialized HunyuanImage-3.0 autoencoder and its loaded weights. Connect it to compatible VAE encoding or decoding nodes: encoding converts an image into the model’s compressed representation, while decoding turns generated latents into a viewable image. The configured architecture uses 32 latent channels and a spatial compression factor of 16, meaning that latent width and height represent image dimensions at one-sixteenth of their spatial resolution. Although its internal architecture includes a temporal dimension, the loader marks it for image use rather than video use. The object also carries device placement, working precision, model-loading support, and architecture-specific memory estimates used by ComfyUI. It is a reusable model object, not an image or an already encoded latent, and it should be paired with workflows that expect the HunyuanImage-3.0 VAE format.

Load HunyuanImage-3.0 VAE Usage Tips:

  • Select the intended HunyuanImage-3.0 VAE file, such as the fp16 or fp32 variant identified by the tooltip. A file appearing in the dropdown only means ComfyUI found it in a VAE model location; it does not establish compatibility.
  • Use this dedicated loader when your installed ComfyUI incorrectly identifies the checkpoint as a Hunyuan Video refiner VAE. The source specifically documents washed-out decoding from that architecture mismatch, despite apparently successful weight loading.
  • Place the checkpoint in ComfyUI’s models/vae directory or another configured VAE location. If a newly installed file does not appear, refresh ComfyUI’s model list or restart ComfyUI.
  • Reuse the loaded VAE across compatible encoding and decoding steps. The node’s tooltip states that one VAE serves all three supported checkpoints, so separate VAE files are not required solely because you switch between those checkpoints.
  • Treat fp16 and fp32 filenames as weight-file choices, not guaranteed runtime precision controls. This node has no precision selector; inspect the loading log’s dtype value to confirm the precision ComfyUI actually resolved.
  • Start with a smaller image resolution and a single image when testing limited GPU memory. Encoding and decoding memory requirements grow with image size, and this architecture can require substantial working memory beyond the space occupied by its weights. The supplied memory estimates help ComfyUI manage loading but do not guarantee that every resolution will fit.
  • Check the console after loading. The node reports the number of loaded, missing, and unexpected keys together with the resolved precision. Zero missing and zero unexpected keys are useful indicators that the checkpoint matches the architecture, although they do not independently verify the entire workflow.

Load HunyuanImage-3.0 VAE Common Errors and Solutions:

Selected VAE file cannot be found

  • Explanation: The node resolves vae_name through ComfyUI’s registered VAE paths and requires the selected file to exist. Loading can fail if a workflow references a file that was deleted, renamed, moved, or never installed. The exact file-not-found message depends on your ComfyUI version.
  • Solution: Install the intended HunyuanImage-3.0 VAE in models/vae or a configured VAE location, refresh or restart ComfyUI, and select its current filename from the dropdown.

Error(s) in loading state_dict for HunyuanImage3VAE / size mismatch

  • Explanation: A message containing size mismatch generally means that a weight in the selected checkpoint has different dimensions from those required by the fixed architecture. This can happen if you select an unrelated VAE or an incompatible checkpoint. The node allows missing and unexpected keys during its final weight-loading step, but incompatible tensor sizes can still stop loading.
  • Solution: Confirm that you selected the package’s intended HunyuanImage-3.0 VAE rather than a Hunyuan Video, Stable Diffusion, or other VAE. If the filename looks correct, verify the download source and replace the file with a known compatible copy.

HunyuanImage-3.0 VAE: ... missing, ... unexpected, dtype ...

  • Explanation: This is the node’s loading-summary message, not automatically an error. Nonzero missing or unexpected counts indicate that some expected weights were absent or some supplied weights did not match the architecture. Loading may continue, but the resulting model may be incomplete or unsuitable.
  • Solution: Check the counts in the console. If either is nonzero, verify that the checkpoint is the correct HunyuanImage-3.0 VAE and obtain a complete compatible file before relying on the resulting images.

CUDA out of memory

  • Explanation: This is a possible PyTorch GPU-memory error rather than a message written directly by the node. It can occur while loading the VAE or during downstream encoding and decoding when model weights and temporary calculations exceed available GPU memory. Large images are particularly demanding for this architecture.
  • Solution: Reduce image resolution or batch size, release other GPU-heavy applications or models, and use ComfyUI’s available memory-management or offloading options. If a downstream node offers tiled processing compatible with this VAE, test that option. Do not assume that selecting an fp16-named file alone guarantees reduced runtime memory.

Checkpoint deserialization or file-reading error

  • Explanation: The checkpoint is read through ComfyUI’s tensor-file loader. An incomplete download, damaged file, unreadable file, or unsupported file contents can cause loading to fail before the specialized VAE is ready. The exact message depends on the file format and underlying loader.
  • Solution: Verify that the download finished, confirm that ComfyUI can read the file, and download a fresh copy from the checkpoint’s trusted source. Renaming an unrelated file to a supported extension does not make it compatible.

Washed-out decoded images despite apparently successful loading

  • Explanation: This is a visual symptom rather than an exception. The source documents that automatic detection can select the Hunyuan Video refiner architecture for this checkpoint and still appear to load the weights successfully, producing a washed-out version of the scene.
  • Solution: Confirm that the VAE connection used by your decoding node comes from “Load HunyuanImage-3.0 VAE,” not another loader elsewhere in the graph. Check that the intended HunyuanImage-3.0 checkpoint is selected and review the dedicated loader’s loading summary. If the symptom persists, also verify that the generated latents and downstream workflow are compatible with this VAE.

Load HunyuanImage-3.0 VAE Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-HunyuanImage3
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

Load HunyuanImage-3.0 VAE