FLUX.2 Klein Ref Latent Controller:
Flux2KleinRefLatentController adjusts how strongly one reference latent influences a Flux2 Klein model during attention processing. It works by scaling the selected reference’s attention data in a cloned model, so you can change its contribution without modifying the original model. You can apply the same strength across the reference or use a directional fade to give some areas more influence than others. This provides a way to experiment with reference influence while leaving the accompanying conditioning unchanged; the visible effect depends on the model and the reference information available when the model runs.
FLUX.2 Klein Ref Latent Controller Input Parameters:
model
A required MODEL input. Supply the model whose reference influence you want to adjust. The node clones it and installs an attention patch on the clone, leaving the supplied model object unmodified. There is no numeric range or default for this input.
conditioning
A required CONDITIONING input. Supply the conditioning that accompanies the model. The node passes it through unchanged, but when spatial fading is enabled, it also looks in its metadata for reference_latents to determine the selected reference’s spatial layout. If that metadata or the selected latent is unavailable, the node can still apply uniform strength when reference tokens are available at runtime. There is no numeric range or default for this input.
strength
A required FLOAT input controlling the multiplier applied to the selected reference’s attention keys and values. The default is 1.0, the minimum is 0.0, the maximum is 1000.0, and the step is 0.05. At 1.0, the selected data retains its original scale before any spatial fade; 0.0 multiplies it by zero; values above 1.0 increase its scale. This is an attention-data multiplier, not a guaranteed percentage of visual influence, so test changes against your actual results.
reference_index
A required INT input choosing which reference to control, counted from zero. The default and minimum are 0, and the maximum is 7: 0 selects the first reference, 1 the second, and so on. The patch acts only when runtime reference-token information contains an entry at this index. When spatial fading is enabled, the node also searches the conditioning metadata for a latent at the same index; if it cannot find one, the selected reference receives uniform scaling instead.
spatial_fade
An optional selection controlling whether strength varies across the selected reference’s spatial positions. The options are none, center_out, edges_out, top_down, and left_right; the default is none. With none, all selected reference tokens receive the same multiplier. center_out gives central positions more weight than positions farther out; edges_out does the reverse. top_down reduces weight from top to bottom, while left_right reduces it from left to right. A fade requires a matching reference latent in the conditioning metadata; otherwise the node falls back to uniform scaling.
spatial_fade_strength
An optional FLOAT input setting how pronounced the selected spatial fade is. The default is 0.5, the minimum is 0.0, the maximum is 1.0, and the step is 0.05. At 0.0, all spatial positions receive equal weight even if a fade mode is selected. As the value increases, the lower-weight positions receive less of the configured strength; at 1.0, positions at the low end of the fade can receive zero weight. It has no effect when spatial_fade is none or no matching reference latent is found.
debug
An optional BOOLEAN input with a default of False. When enabled, the patch prints a [RefLatentController] line when it processes a valid selected reference, showing the block index, reference index, token slice, and configured strength. This helps you check whether the selected reference is being processed. It does not change the scaling calculation; leave it off when you do not need diagnostic output.
FLUX.2 Klein Ref Latent Controller Output Parameters:
model
The first output is a MODEL: a clone of the supplied model with the reference-weighting attention patch installed. Connect this output wherever you want the adjusted model to be used. The patch applies its scaling when attention runs and the selected reference’s token information is present; receiving this model output alone does not mean a visible change has already occurred.
conditioning
The second output is CONDITIONING. It is the same conditioning value passed into the node, returned unchanged for connection to later workflow steps. It may provide reference-latent metadata used to calculate a spatial fade, but the node does not rewrite the conditioning or embed the adjusted strength in it.
FLUX.2 Klein Ref Latent Controller Usage Tips:
- Start with
strengthat1.0andspatial_fadeatnoneto establish a baseline, then change one setting at a time so you can judge its effect. - Set
reference_indexto the zero-based position of the reference you intend to adjust. If you have several references, check their order before assuming that0targets the one you want. - For an even adjustment across the reference, leave
spatial_fadeatnone. This also avoids depending onreference_latentsmetadata for the fade calculation. - To vary influence by position, choose a fade mode and begin with the default
spatial_fade_strengthof0.5. Increase it for a stronger positional difference or set it to0.0to compare against even weighting. - Enable
debugtemporarily when you need to confirm that the selected reference is being processed. Look for the[RefLatentController]line in the process output, then turn debugging off when finished.
FLUX.2 Klein Ref Latent Controller Common Errors and Solutions:
Missing required input: model or conditioning
- Explanation: The node requires both a
MODELandCONDITIONINGconnection. A workflow may report a missing-input validation error when either is absent. - Solution: Connect a compatible model to
modeland conditioning toconditioningbefore running the workflow.
Invalid value for strength, reference_index, or spatial_fade_strength
- Explanation: The interface limits
strengthto0.0–1000.0,reference_indexto0–7, andspatial_fade_strengthto0.0–1.0. Values outside these ranges may fail interface or workflow validation. - Solution: Bring the value into its stated range. Check the value supplied by any connected control as well as the value shown on the node.
Invalid spatial_fade option
- Explanation: The interface offers only
none,center_out,edges_out,top_down, andleft_right. An unsupported value may be rejected by workflow validation; the helper also has no fade calculation for an unrecognized mode. - Solution: Select one of the listed options, or use
nonefor uniform strength.
No visible change after adjusting strength
- Explanation: The patch returns without changing attention data when runtime
reference_image_num_tokensis absent or does not contain the selectedreference_index. This is normally a silent no-op, not a specific error message from the node. - Solution: Check that your workflow supplies reference information to the model at runtime and that
reference_indexmatches an available reference. Temporarily enabledebug; a[RefLatentController]line indicates that a valid selected reference reached the patch.
Spatial fade appears to have no effect
- Explanation: The node applies a fade only when it finds the selected latent under
reference_latentsin the conditioning metadata. Without it, scaling is uniform. Aspatial_fade_strengthof0.0also makes all calculated spatial weights equal. Neither condition produces a dedicated error message in this source. - Solution: Confirm that the supplied conditioning contains the selected reference latent, choose a fade mode other than
none, and use a fade strength above0.0.
No [RefLatentController] debug line appears
- Explanation: Debug output is printed only when
debugis enabled and the patch processes a selected reference with a valid runtime token entry. The node itself does not print a warning when that entry is missing. - Solution: Turn on
debug, run the workflow through model execution, and check the process output. If the line is still absent, verify the reference setup andreference_index.
