Nucleus-Image VAE Loader

Every pack ships a VAE loader and they're usually interchangeable. This one isn't. Nucleus-Image VAE Loader loads a very specific VAE - the AutoencoderKLQwenImage, the same 16-channel architecture Qwen-Image uses - and it exists precisely because you can't just grab the SDXL VAE sitting in your models folder.

Why it can't be the normal VAE loader

The KB's concepts doc spells out the trap: SD1.5/SDXL use a 4-channel latent, and modern models quietly jumped to 16 channels. Nucleus-Image is one of the 16-channel crowd. If you feed a 4-channel VAE's weights into a 16-channel model, you get noise or flat colour - not a subtly wrong image, actual garbage. The README's FAQ puts it bluntly: confirm you're using the correct model file, don't use another model's VAE. The built-in VAELoader has no idea how to build this architecture, which is why this pack has its own.

The good news: the VAE is tiny. nucleus_image_vae.safetensors is about 122 MB in FP8, which is a rounding error next to the 16.9 GB transformer. Skipping it to save disk space is a false economy - you can't decode anything without it.

How it works

The loader reads the VAE's config from the pack's bundled configs/vae_config.json, builds the model on the offload device (CPU RAM), then loads the FP8 weights straight in. Like the text encoder, it stays parked on CPU until the VAE Decode node actually runs, at which point the VAE is moved to the GPU, used, and offloaded again. If the loader returns in milliseconds with your GPU untouched, that's working as intended.

Inputs and output

• model_name - dropdown of files in ComfyUI/models/vae/. You want nucleus_image_vae.safetensors (FP8, the tested path); the bf16 variant (≈243 MB) is optional.
• precision - bf16 (default), fp16, or fp32. bf16 is what the author verified.

Output is a NUCLEUS_VAE object that feeds the VAE Decode node.

Installing and troubleshooting

Standard pack install - ComfyUI Manager (search "Nucleus-Image") or:

cd ComfyUI/custom_nodes
git clone https://github.com/a180265/Nucleus-Image-comfyui-beta

restart, then drop the VAE file from the Nucleus-Image Hugging Face repo into models/vae/. The pack's usual heavy dependencies (torch 2.11+, diffusers 0.38+, transformers 4.57+) apply - the VAE itself doesn't need them, but the loader file imports them at module load.

Troubleshooting is a two-item list. Images look dark or grey: wrong VAE file, or the file isn't where the loader expects. The README's "images too dark" FAQ is answered by "check the VAE loader is using the correct model file." Empty dropdown: file missing from models/vae/ or ComfyUI started before you placed it - drop it in and restart. And a heads-up for the VAE tinkerers: the community habit of hot-swapping VAEs across models to chase color is exactly the thing that produces grey sludge here. The 16-channel latents are normalized with model-specific mean/std, and this loader handles that internally - feed it the file it was built for and leave the experiment for another pack.