Patch Wan Upscale VAE (VAE Utils)

The Wan 2.1 upscale VAE is not a normal VAE, and ComfyUI's stock VAE Decode has no idea what to do with it. Feed it latents and you get a wrong-shaped tensor, dark burned-out pixels, or an outright crash - the (1, 1, 12) type errors people hit when they drop it into a plain loader. Patch Wan Upscale VAE (VAE Utils) is the one-node fix that makes the thing decode correctly.

Here's the setup that makes it worth your time. Wan 2.1 (Alibaba's open video/image family, per the KB) has a hard native-resolution ceiling like every diffusion model - you generate at 480p/720p and then climb. This pack's approach is to decode through an upscale VAE instead of decoding then running ESRGAN: the Wan2.1 VAE 2x imageonly real v1 model doubles the pixels at decode time, no separate upscale pass, no invented detail. It's the "generate at native, then climb" philosophy from the upscaling playbook, built into the VAE itself. This node is the part that makes that trick actually work.

What the node actually does

The Wan 2.1 upscale VAE is a 3D causal VAE whose decoder emits packed channels - more channels than the image has, in a perfect-square ratio (16 channels where you'd expect 3, give or take), so a naive decode hands you a blob with the wrong shape. Patch Wan Upscale VAE fixes this by:

1. Detecting whether your VAE is really a Wan upscale VAE - it checks the decoder's channel counts and latent dimensionality, not the filename.
2. Wrapping the VAE's decode and decode_tiled with corrected versions that call the original decoder, then unpack the packed channels back into spatial pixels via pixel shuffle, clamp the [-1, 1] raw output into [0, 1] (ComfyUI saves anything below 0 as black - that's your "why is it dark" moment), and flatten the 5D video tensor to plain frames.
3. It's idempotent - patch it twice and nothing breaks, it just hands you a patched copy.

The name is slightly misleading in one way: it doesn't upscale anything itself. The upscaling lives in the VAE's weights. This node is the translator that lets stock ComfyUI talk to them.

Inputs and outputs

One input, one output - this is about as simple as nodes get:

• vae (VAE, required) - the VAE you want patched. Load it with the pack's own "Load VAE (VAE Utils)" node (which auto-patches, more on that below), or the stock Load VAE.
• VAE (output) - the same VAE, patched. Wire it into any VAE Decode node. The pack's "VAE Decode (VAE Utils)" is the natural partner, but a stock decode node works too once the patch is in place.

Installing it

The pack has zero extra Python dependencies - "no extra requirements outside of what ComfyUI already uses," per the README. Install via ComfyUI Manager (search "ComfyUI-VAE-Utils") or:

cd ComfyUI/custom_nodes
git clone https://github.com/spacepxl/ComfyUI-VAE-Utils

Then restart ComfyUI and grab the model: download Wan2.1_VAE_upscale2x_imageonly_real_v1.safetensors from spacepxl/Wan2.1-VAE-upscale2x into ComfyUI/models/vae/. The pack's own workflow/workflow_wan_t2i_upscale2x.png shows the intended wiring.

Where people get burned

• The requires a Core-loaded 3D VAE with packed decoder channels error. The node refuses to patch a VAE that doesn't match the Wan upscale signature - so if you plug in a regular SDXL, Flux, or Qwen VAE, it throws on purpose. That's a feature, not a bug: you've grabbed the wrong model.
• Dark or black output. If you decode the upscale VAE through a path that wasn't patched, the raw decoder output stays in [-1, 1] and ComfyUI clamps the negatives to black. The source even guards against a ComfyUI regression (PRs #11405/#11406) that reintroduced exactly this. Patched decode fixes it.
• WanVideoWrapper latents. If your latents come from kijai's WanVideoWrapper, the README is explicit: un-normalize them first with the latent rescale trick, or everything downstream decodes wrong.
• You might not need this node at all. The pack's "Load VAE (VAE Utils)" node auto-detects the upscale VAE and patches it for you. Reach for the manual patch node when the VAE reaches your graph through some other route - a stock loader, a baked checkpoint, an imported workflow.

One last thing worth knowing: the author, spacepxl, is the Wan community person behind the Control LoRAs for Wan and the HunyuanVideo training datasets - this isn't a random throwaway pack. It's the niche-but-serious corner of Wan tooling, and this node is the key that unlocks the upscale VAE for anyone not using the pack's own loader.