Resolution Bucket

Resolution Bucket exists to fix the thing that silently ruins datasets: your images aren't all the same size, and the trainer would rather they were. A character set naturally mixes close-ups and full-body shots, portrait and landscape crops. You could squash everything to one resolution, but then you're telling the model that composition doesn't matter and teaching it one aspect ratio it will reproduce forever. Or you bucket - group the images by resolution, train each group together, and let the model see the variety.

This is the same multi-resolution bucketing that external trainers (ai-toolkit ships it by default) moved to years ago, and the KB calls it the default rather than an optimization on modern bases. This node brings it to ComfyUI's built-in trainer. It's part of ComfyUI core, landed with the training family in late 2025, and it's small: two inputs, two outputs, no widgets.

How it works

You feed it the parallel lists from Make Training Dataset - one latent dict and one conditioning list per image. The node flattens everything down to individual samples, keys each sample by its exact (height, width), and groups same-size samples together. Each group gets stacked into a batch - so all your 768×1024 portraits become one (N, C, 768, 1024) latent tensor with matching conditioning - and each resolution comes back as its own entry in the output lists. The console logs how many buckets it created and how many samples landed in each.

Inputs and outputs

• latents - the list of latent dicts from Make Training Dataset.
• conditioning - the matching list of conditioning lists. The two lists must be the same length, and each latent dict's batch must line up with its conditioning; mismatch and you get a clear error rather than silent misalignment.

Outputs are latents and conditioning again, but now batched: one entry per unique resolution, each holding all the samples of that size. Wire them into Train LoRA and flip on its bucket_mode toggle - that's the whole point. Without bucket mode, Train LoRA falls back to treating varied resolutions as a per-sample multi-resolution pass; with it, same-size samples batch together efficiently, which is faster and more predictable.

What trips people up

• Forgetting bucket_mode. The node's purpose is to feed bucket-mode training. Run it and connect the output but leave the trainer's toggle off, and you've added a middleman for nothing.
• Expecting resizing. This node never changes pixel dimensions - it only groups samples that already share a resolution. If your set is a pile of 512, 768, and 1024 images, you'll get exactly three buckets, not a resized uniform set. Crop and resize upstream if that's what you want.
• Very uneven buckets. One bucket with 40 samples and another with 2 is fine mechanically - the trainer samples buckets weighted by size - but it's a signal your set is lopsided, and curation still beats bucketing as a fix.
• The typical sizes. Don't overthink it. A 512/768/1024 spread is the well-trodden path, and the KB's published runs stretch that as far as 1536 on modern bases. What matters is that your model sees the aspect ratios you'll want at inference.

Why it matters more than it looks

Bucket mode is how you get a LoRA that handles portrait and landscape without training one into the other. It's also the difference between a trainer that chokes on varied sets and one that quietly absorbs them. For a beginner it reads like an optimization detail; for anyone who's trained a style across mixed sources, it's the difference between a flexible LoRA and one that only works in the exact crop you fed it.