HunyuanImage-3.0 Looped Diffusion:
HunyuanImage3Looping, displayed as “HunyuanImage-3.0 Looped Diffusion,” modifies how HunyuanImage-3.0 processes an image during generation by running a selected group of transformer layers twice per sampling step. Transformer layers are stages of the model’s internal processing; repeating a group gives the model another pass through that processing without retraining it. This training-free approach, described as Looped-DiT, can help with demanding image-generation tasks such as dense text, closer adherence to your prompt, or counting objects. Repeating earlier layers is intended to help dense text and prompt adherence, while repeating middle layers can help counting but may also cause subjects to disappear. The node changes the model’s processing behavior rather than increasing the number of sampling steps or generating an image itself. Its documented trade-off is approximately 15–27% more time per sampling step, and improvements depend on your prompt and the selected repetition strategy.
HunyuanImage-3.0 Looped Diffusion Input Parameters:
model
The required MODEL connection supplies the model whose processing you want to modify. Use a compatible HunyuanImage-3.0 model, because the repetition setting is read by the HunyuanImage-3.0 implementation shown in the provided code. The node clones the supplied model wrapper and adds the looping configuration to that clone, leaving the incoming model’s configuration unchanged. This lets you keep an unmodified branch for comparison while using the modified branch for generation. The node does not load model weights, retrain the model, or directly change your prompt. There is no numeric minimum, maximum, or default value for this connection; you must supply a MODEL from your workflow.
preset
The required COMBO selection determines which group of layers is repeated and how strongly the repeated processing updates the model’s internal state. The default is early x2. The supplied preset definitions are early x2, which repeats layers 4–9 with a full-strength update of 1.0; mid x2, which repeats layers 11–20 with a full-strength update of 1.0; and mid x2 half, which repeats layers 11–20 with an update scale of 0.5. These layer numbers follow the implementation’s indexing, and the end of each configured span is exclusive. Choose early x2 when testing dense text or prompt adherence, and consider the middle-layer presets when testing object counts, keeping in mind that they may drop subjects. In mid x2 half, each repeated layer blends its incoming internal state and its newly computed result equally, making the repeated updates less strong than in mid x2. “Half” does not mean half the repeated layers, half the sampling steps, or half the processing time. This is a fixed-choice setting, so numeric minimum and maximum values do not apply.
HunyuanImage-3.0 Looped Diffusion Output Parameters:
MODEL
The MODEL output is the cloned model configured to use the selected layer-repetition preset. Internally, the node stores this configuration under hy3_loop in the model’s transformer options, which the compatible HunyuanImage-3.0 implementation uses during processing. Connect this output to the model path used by your sampler so that subsequent generation uses the modified behavior. It is still a MODEL connection, not an image, conditioning result, or collection of newly trained weights. Its importance is that it carries the looping behavior forward in your workflow while allowing the original incoming model configuration to remain available separately.
HunyuanImage-3.0 Looped Diffusion Usage Tips:
- Start with
early x2, the default preset, when your main concern is dense text or following a detailed prompt. Treat it as a targeted experiment rather than a guaranteed improvement. - Try
mid x2for prompts where the number of objects matters. Check both the count and the presence of every requested subject, because the node description explicitly warns that middle-layer repetition may drop subjects. - Compare
mid x2 halfagainstmid x2if full-strength middle-layer repetition changes the composition too much. It reduces the strength of each repeated update, but it does not eliminate the extra layer executions or guarantee that missing subjects will return. - Keep your prompt, seed, sampler settings, resolution, and other model modifications unchanged when comparing presets. This makes it easier to identify what the looping setting actually changes.
- Route the node’s MODEL output into your sampling path. If the sampler still receives the original model, the looping configuration on the cloned branch will not affect that generation.
- Budget for the documented increase of approximately 15–27% in time per sampling step. Test a small batch before committing to a long generation run, since actual timing depends on your setup.
- Use separate branches for preset comparisons. Applying this node again to the same model branch replaces its existing
hy3_loopsetting rather than combining multiple looping presets.
HunyuanImage-3.0 Looped Diffusion Common Errors and Solutions:
Missing required input: model
- Explanation: This is a descriptive validation issue rather than an exact error string supplied by the node. The node requires a MODEL connection and cannot configure looping without one.
- Solution: Connect a compatible HunyuanImage-3.0 MODEL output to
model, then confirm that the upstream model-loading node completes successfully.
Invalid preset selection or KeyError
- Explanation: The node looks up the selected value directly in
LOOP_PRESETS. If an edited workflow or programmatic call supplies an unknown preset name, Python can raise aKeyErrorcontaining that value. ComfyUI may instead reject the selection during input validation. - Solution: Select
early x2,mid x2, ormid x2 halffrom the dropdown. If an older workflow contains an unavailable value, reselect a valid preset or recreate the node.
Looping has no visible effect
- Explanation: This is a troubleshooting symptom, not a defined error message. The sampler may still be connected to the original model, or the model implementation may not read the HunyuanImage-3.0-specific
hy3_loopsetting. Even with correct wiring, a particular prompt may not show an obvious visual improvement. - Solution: Confirm that your sampling path receives this node’s MODEL output and that you are using the compatible HunyuanImage-3.0 implementation. Compare against an unmodified branch using the same seed and settings, and test prompts involving the intended targets, such as dense text or object counts.
Generation takes longer after enabling looping
- Explanation: This is expected behavior rather than an error: the selected transformer layers are executed again. The documented overhead is approximately 15–27% per sampling step, although your actual timing may differ.
- Solution: Compare timing with the same workflow bypassing this node to establish the added cost. Use looping where its visual benefit justifies the extra time, and do not expect
mid x2 halfto halve that overhead, because it still executes the repeated layers.
Subjects disappear or the composition becomes less faithful
- Explanation: This is a documented possible side effect of the middle-layer presets, not a software exception. Improvements in counting can come with the loss of requested subjects, and repeating layers does not guarantee better results for every image.
- Solution: Compare
mid x2 halfwithmid x2to test gentler repeated updates, switch toearly x2when prompt adherence is the priority, or bypass looping if the unmodified model preserves your composition better. Check several seeds before choosing a preset for a larger batch.
