STARFlow Checkpoint Loader

Every STARFlow text-to-image run starts on this node, so let's be honest about the context you're stepping into: STARFlow is Apple's open-weights normalizing-flow model from late 2025. The architecture is genuinely interesting - it flips diffusion around into a two-way flow and samples fast - but the community reception was, shall we say, measured. "Killer model for 2021" was a real sentiment in the release threads. The interesting part was never the demo quality; it was that a normalizing flow T2I model existed at all. If you're here, you want to see what that architecture does, and this loader is the door.

It's also the node that will fight you the most, because a STARFlow checkpoint is not a ComfyUI checkpoint. There's no MODEL/CLIP/VAE triple in one file here - this loader builds the transformer architecture from a config preset, then pours the weights in.

What it loads and how

STARFlowCheckpointLoader reads from ComfyUI/models/starflow/ (it also scans your diffusion_models folder, so files dropped there show up too). It accepts .pth or .safetensors. On the backend it parses the starflow_3B_t2i_256x256 config preset - that's your config_name, and today it's the only option - builds the transformer, and loads the state dict, tolerating model/state_dict wrappers from various export formats. Then it moves the thing to GPU and locks it. Output is a STARFLOW_MODEL, which only the STARFlowSampler knows how to consume.

The inputs you'll actually touch

• checkpoint_name - the file, picked from a dropdown. This is the starflow_3B_t2i_256x256.safetensors from the model repo.
• config_name - the architecture preset. Leave it on starflow_3B_t2i_256x256.
• vae_downscale (optional, default 8) - the VAE's spatial downscale. The node hard-errors if img_size isn't divisible by this, which for the default 256×256 model and 8 means 32×32 latents. Don't touch it unless you know why.
• text_dim (optional, default 2048) - the text encoder's hidden size. FLAN-T5-XL is 2048, which is what STARFlow uses, so you can usually ignore this too.

In other words: the dropdowns that matter are checkpoint_name and config_name. Everything else has a correct default already.

Installing the model

Install the pack once (see the STARFlow VAE Decode article for the exact commands - it's the same clone, same requirements.txt). Then:

# put the 3B checkpoint where this node looks for it
mkdir -p ComfyUI/models/starflow
# move starflow_3B_t2i_256x256.safetensors into that folder
# plus FLAN-T5-XL encoder weights into ComfyUI/models/text_encoders/

Don't skip the text encoder - STARFlowT5TextEncode needs it, and a loader without a conditioning source is a workflow that generates nothing.

Gotchas

The model is 3B parameters, so this node eats a real chunk of VRAM just to hold weights. Don't be surprised when the first load takes a while - it builds the full transformer from scratch on every cold start. And if you drag in some other model's checkpoint and get a shape-mismatch wall of errors, that's expected: the state dict loader is strict about matching this architecture. Use the shipped STARFlow file. The two knobs that say "for advanced users" are in the right place.