VAE Decode (VAE Utils)

If you landed here, odds are you tried to run spacepxl's Wan 2.1 "upscale" VAE and the stock VAE Decode node blew up with something like Cannot handle this data type: (1, 1, 12), |u1. This is the node that makes it work. That's the short version.

The longer version is more interesting. The Wan 2.1 VAE has quietly become the community's favorite decoder to bolt onto Qwen-family latent models - Qwen-Image, Qwen-Image-Edit, Anima, Krea 2. Those all ship the Qwen VAE, which was retuned for legible text and gave up fine texture to get there, so people swap in Wan's decoder to claw the detail back. It's not a hack: Qwen literally froze Wan's encoder, so the two share an identical 16-channel latent space and the decoder is a legitimate drop-in. spacepxl went one further and trained a Wan VAE variant that decodes at 2x resolution - a free upscale baked into the decode step. Lovely in theory. In practice ComfyUI's built-in decode nodes don't understand its channel layout, so they throw. This node does.

What it actually does

It decodes a latent to pixels like any VAE decode, with two things bolted on. First, optional auto-detected upscaling: point it at the 2x VAE and it decodes straight to double resolution, no separate upscale pass. Second, optional tiling, so a big decode doesn't torch your VRAM.

The inputs that matter

• samples (LATENT) and vae (VAE) - the two you always wire. Feed vae from Load VAE (VAE Utils), not the stock loader; they're a matched pair.
• upscale (INT, default -1) - the clever one. -1 means "auto": it asks the VAE how much it upscales and does that (2x for the upscale VAE, 1x for a normal one). You rarely touch it. Set an explicit number only to override the auto-detection.
• tile (BOOLEAN, default off) - flip on for low-VRAM machines or huge latents. Off is fine for normal image sizes.
• tile_size (512) and overlap (64) - the spatial tile grid. Bigger tiles mean fewer seams but more VRAM; the overlap blends tile edges so you don't get a patchwork. The defaults are sane, so only tune if you actually see seams or run out of memory.
• temporal_size / temporal_overlap - these exist because Wan's VAE is a 3D video autoencoder that compresses time as well as space, decoding video latents in chunks. For single images they don't matter.

Output is a single IMAGE, wired straight into Save Image, a preview, or a downstream upscaler.

Installing it

No package to fight with - the README is blunt about it: "No extra requirements outside of what ComfyUI already uses." Two ways:

• ComfyUI Manager: search ComfyUI-VAE-Utils, install, restart.
• Terminal: cd ComfyUI/custom_nodes && git clone https://github.com/spacepxl/ComfyUI-VAE-Utils, then restart ComfyUI and hard-refresh with F5.

Then grab the model, because the node is pointless without it. Download Wan2.1_VAE_upscale2x_imageonly_real_v1.safetensors from huggingface.co/spacepxl/Wan2.1-VAE-upscale2x into ComfyUI/models/vae/.

Where people get burned

• The data-type error (Cannot handle this data type: (1, 1, 12), |u1) means you decoded the upscale VAE through a stock node. Swap in this one plus Load VAE (VAE Utils). This whole pack exists to fix exactly that.
• No upscale happening. If you expected 2x and got 1x, you're not on the upscale VAE - a plain Wan VAE won't magically double resolution. Check what file your loader points at.
• Latents from Kijai's WanVideoWrapper. The README flags this specifically: WanVideoWrapper normalizes its latents differently, so you have to un-normalize (rescale) them before decoding or the image comes out wrong. If a decode looks blown-out or crushed and the source is a WanVideoWrapper graph, that's your culprit.

Honest take: this is a single-purpose bridge node. If you're not running the Wan upscale VAE on a Qwen-family model, you don't need it - stock VAE Decode and VAE Decode (Tiled) are fine. But if you are chasing that "better VAE, and it upscales for free" trick everyone keeps posting about, this is the node the trick actually runs on.