Hunyuan 3D 2.1 VAE Loader

If you're coming from Stable Diffusion, "VAE" means the little image encoder/decoder that turns pixels into latents and back. The Hunyuan3D VAE is a different animal: it's a geometry VAE that decodes latents into 3D shape - vertices, faces, an octree of occupancy. Hy3D21VAELoader is the node that loads it, and it's the silent partner to Hy3DMeshGenerator. Generator makes latents, this VAE turns them into something you can actually hold.

The node has exactly one real input: model_name, a dropdown of everything in ComfyUI/models/vae. You need hunyuan3d-vae-v2-1.ckpt from the Tencent Hunyuan3D-2.1 HuggingFace repo, placed in models/vae/. The output is a HY3DVAE that you wire straight into Hy3D21VAEDecode - and only there. No other node in the pack wants a HY3DVAE, so this loader exists to feed exactly one consumer.

How it works

The loader reads the checkpoint and builds a ShapeVAE with a baked-in architecture config - 4096 latents, 1024 hidden width, 8 encoder / 16 decoder layers, a fixed scale factor, and so on. It then loads the weights and drops the whole thing into fp16. The optional vae_config input lets you override that architecture, which you should never do unless you're debugging a custom checkpoint; the hardcoded defaults are the correct ones for the stock hunyuan3d-vae-v2-1.ckpt. Setting a wrong config produces garbage geometry, not an error.

Installing it

The loader needs the pack installed first:

cd ComfyUI/custom_nodes
git clone https://github.com/visualbruno/ComfyUI-Hunyuan3d-2-1
cd ComfyUI-Hunyuan3d-2-1
pip install -r requirements.txt

Then put the VAE checkpoint where the dropdown can see it:

ComfyUI/models/vae/hunyuan3d-vae-v2-1.ckpt

Restart ComfyUI. The README stresses Windows 11 + Python 3.12 + Torch ≥ 2.6.0 + cu126; the closer you are to that, the smoother everything else goes. And don't forget this pack also needs the two C++ extensions (custom_rasterizer, mesh_inpaint_processor) installed even for a shape-only workflow - the requirements file doesn't cover them, the README does.

Common issues

The classic failure is an empty dropdown, which just means the .ckpt isn't in models/vae/ (or ComfyUI wasn't restarted). The subtler one: an out-of-memory error during decode is usually not this node's fault - the VAE decode is chunked and memory-hungry, and the knobs to fix it live on Hy3D21VAEDecode (num_chunks, octree_resolution), not here. This node is boring, and boring is good: if it loads without error, you're past the worst of the install.