ModelPack VAE

Washed-out grey images, or a workflow that dies at the decode step with a missing-VAE error - those are the two symptoms that send people looking for a VAE loader. ModelPack VAE is one, but with the weights coming from an OCI registry instead of a folder.

Why a VAE loader still matters

The VAE converts between latent space and pixels. Both directions, every run. It is not a filter and it is not optional - the KB's framing is right that a VAE is not "the thing that fixes colors," because without it there is no picture at all. What it can be is wrong: pair a checkpoint with a VAE it wasn't trained against and you get a poor conversion, most typically the greyish, faded look everyone blames on the sampler.

Two things changed by 2026 and both make this node more relevant than it used to be. First, the VAE is often a separate file you download yourself - Z-Image, Flux 2 Klein and the Wan models all list the VAE on the model card next to a separate text encoder, so a downloaded workflow that errors on a missing VAE usually means somebody grabbed the diffusion weights and skipped the companions. Second, the VAE became a quality lever again for the opposite reason: on 2026 models the complaint is over-smoothing, and the usual fix is swapping one VAE for another rather than loading any VAE at all.

Worth saying plainly so you don't chase a non-problem: some models have no VAE. The pixel-space generation wave - HiDream-O1 and friends - encodes raw pixels directly. A workflow with no VAE loader is not automatically broken.

Inputs and output

Two fields and one output. It's the simplest node in the pack.

• reference - the OCI reference for the VAE artifact, e.g. registry.example.com/models/wan-vae:v1. Empty = local mode.
• file - with a reference, the path inside the artifact; without one, a filename from models/vae. Subfolders work if you organize your VAEs that way, since the lookup goes through ComfyUI's own folder resolver.

Output is VAE, into VAE Decode (and VAE Encode if you're doing img2img).

How it loads, and why that's safer than it looks

The node reads the file with ComfyUI's load_torch_file - metadata included - constructs comfy.sd.VAE from that state dict, and then calls throw_exception_if_invalid() immediately. That last call is the useful part: validation happens at load, so if you point it at something that isn't a VAE you get a clear error from the node instead of a confusing explosion three nodes downstream at decode time. Same loader path as core's VAE Loader, same metadata handling.

Installing it

Manager: search ComfyUI ModelPack (cerussite). Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/SiLeader/ComfyUI-ModelPack comfyui-modelpack
python -m pip install -r comfyui-modelpack/requirements.txt

Restart after. Dependencies are modelpack-client plus oras, jsonschema and zstandard - nothing that rebuilds torch or touches your CUDA install. Use the interpreter that runs ComfyUI (portable Windows builds: python_embedded\python.exe), and note the floors: Python 3.10+, ComfyUI 0.22.0+.

Pull behaviour and the extension trap

Artifacts land under ComfyUI/models/modelpack/vae/<hash>/, hash = the first 24 characters of the SHA-256 of the reference. Digest references (repo@sha256:…) pull once and never check the registry again - offline-safe. Tag references re-pull on first use after each restart and quietly fall back to your local copy if the registry is unreachable. Private registries authenticate with docker login credentials from ~/.docker/config.json.

Here's the one that will actually stop you. The node only considers pulled files whose extension ComfyUI's loader recognizes - the .safetensors / .ckpt / .pt family. .gguf is not in that set unless you have the GGUF node pack installed, because that's what registers the extension. So an artifact that keeps everything quantized in GGUF will produce "the artifact has no model file with a supported extension," and it isn't lying - there's a real file in there that this node can't hand to ComfyUI. Check how the artifact stores its weights before you blame the node.

The other common stumble is mode confusion: an empty reference with a file you haven't downloaded gives a file-not-found against your local models/vae folder, not a pull. The two fields swap meaning depending on whether reference is filled, and that catches everyone once.

Would I install the whole pack for this node? No. If you only ever need a VAE from disk, core's VAE Loader is right there and its dropdown lists your files. This one earns its place when the VAE is a versioned artifact you want a workflow to pin by digest, or when you're already pulling the diffusion model from the same registry and would rather not have one file arrive automatically and the other arrive by hand.