Dynamic Checkpoint Loader (Universal)

This is the heart of the ComfyUI-cluster pack: a universal checkpoint loader that can switch between a classic SD1.5/SDXL checkpoint and a fully split Flux pipeline (diffusion model, VAE, and text encoders in separate files) without you rebuilding the graph. The "Universal" in its display name is doing real work, not marketing.

It earns that name because of what's behind it - a model_registry.json in the pack folder that knows, for each of roughly a hundred checkpoints, what type it is, where it lives, how much VRAM it wants, and which VAE/CLIP files it requires. The loader doesn't guess; it reads that registry and loads the right pieces the right way.

How it works

You give it a checkpoint name and a model_type from the menu: auto, sdxl, sd15, flux, svd, hunyuan, or wan. With auto, it resolves the type from the registry. It then searches ComfyUI's model folders - and here's a smart touch, it searches across checkpoints, diffusion_models, and unet for checkpoints, and clip/text_encoders for CLIP, so a model registered with the wrong folder type still gets found. custom_path points at an external model root.

Two things make it genuinely dynamic:

1. Logical fallback. If the requested checkpoint isn't on disk, it doesn't just crash - it walks the registry, from same group+category+type down to same type, and loads the best enabled model that actually exists. You get a loud !!! MISSING MODEL !!! in the console and a clear message, but the workflow keeps running on a sibling model.

2. Mandatory-component handling. Models like Flux and Wan need a separate VAE and CLIP (often a split clip_l + T5). If the registry marks required_vae or required_clip for a model, the loader overrides whatever you set and loads those files - with the correct CLIPType for Flux, including comma-separated split-CLIP loading. Your manual vae_override and clip_override inputs exist for when you know better than the registry.

The outputs that matter

The familiar MODEL, CLIP, and VAE outputs feed your sampler, encoders, and decoder. The fourth, debug_info, is a full search log - paths tried, folder strategy used, fallback chosen, overrides applied. When something loads the wrong thing or fails to find a file, this string is the first place to look. In the pack's workflows it's piped into a LiveStatus node so you can read it without digging.

How to install it

It ships in the GeekatplayStudio/ComfyUI-cluster pack. ComfyUI Manager: search "ComfyUI-cluster". Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/GeekatplayStudio/ComfyUI-cluster

Restart ComfyUI. The nodes have no Python dependencies of their own, but the loader is useless without the registry being in sync with your disk - run manage_models.bat (or python sync_registry.py --sync) after moving or deleting models, or the loader will happily fall back to the wrong checkpoint.

Troubleshooting

The main failure mode is a FileNotFoundError whose message ends in "no suitable fallback discovered" - that means the checkpoint isn't on disk, isn't in the registry, or every same-type candidate is disabled. Fix the registry with sync_registry.py --sync, or run the pack's install.bat to actually download what's missing. Note the installer is a GUI tool that pulls models from Civitai and HuggingFace (set HF_TOKEN first for gated HF files). And don't be surprised when a Flux workflow demands VAE/CLIP files that aren't downloaded yet - check the registry's required_vae/required_clip fields for the model you picked and install those too.