HuggingFace VAE Loader

If you've ever seen a perfectly-reasoned image come out grey and washed out, you already know why this node exists: the model needs a VAE, and the checkpoint didn't come with one. The HuggingFace VAE Loader grabs a VAE straight from a Hugging Face repo - or a local folder - and hands you a ready-to-wire VAE output. No hunting through model pages, no manual file moves into models/vae.

There's one catch you need to know before anything else, because it will save you a confusing ten minutes: despite the node description saying "Downloads a model from Hugging Face," it does not download anything. The code resolves the repo ID inside your local huggingface_hub cache (HF_HUB_CACHE) and reads the files from there. If the repo isn't already cached, it raises FileNotFoundError and literally tells you to run hf download {repo_id} first. So the real workflow is: download once (with hf download black-forest-labs/FLUX.1-dev, or ComfyUI's built-in Hugging Face model downloader, or any tool that populates the HF cache), then load here as many times as you want, offline-friendly.

What it loads and how

Give it a repo_id and it finds the checkpoint in the cache, then feeds the weights into ComfyUI's own VAE class. It handles both single-file checkpoints (the default filename is ae.safetensors, which is exactly what FLUX.1-dev ships) and sharded ones - point filename at the index file like model.index.json and it merges the shards for you.

The defaults are telling: repo_id defaults to black-forest-labs/FLUX.1-dev. That's the FLUX VAE, and it matters because VAEs aren't interchangeable. FLUX uses a 16-channel latent; SD 1.5/SDXL use 4. Slap the wrong one on and you don't get a subtly worse image - you get noise or flat color, because the latent dims don't line up at all. Match the VAE architecture to the model you're generating with.

The inputs that matter

• repo_id - a Hugging Face repo ID, an absolute path (/path/to/model), or a relative path like ./models/... from your ComfyUI root. Local paths skip the cache entirely.
• subfolder - where the VAE lives inside the repo or folder (FLUX keeps it at the root; some repos nest it under vae/).
• filename - the checkpoint file. The default ae.safetensors is right for FLUX. Leave it blank to auto-detect, or point at an index.json for sharded repos.

Output is a single VAE, which feeds straight into VAE Decode, VAE Encode, or any node that wants a VAE socket.

Installing it

It ships in Duanyll Nodepack. Easiest path is ComfyUI Manager - search "Duanyll Nodepack" and install. Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/Duanyll/duanyll_nodepack

Then restart ComfyUI. The pack pulls its own requirements on load (huggingface-hub, safetensors, and friends), and huggingface-hub is what your cache lives in. Note the README is still the cookiecutter template - this is a young pack - so the code, not the docs, is the source of truth for behavior like the no-download thing.

Where people get burned: they set a repo ID for a model they've never downloaded, hit run, and get a cache-miss error. Download first, then load. And if the decoded image looks wrong, double-check the VAE's latent channels match your model - that's the classic grey-flat-image failure, covered well in the modidex knowledge base on VAE concepts.