Load LoRA (SimpleTuner Flux 2)

If you've ever dragged a SimpleTuner-trained Flux LoRA into the standard ComfyUI LoRA loader and watched the console fill with lora key not loaded: transformer_single_transformer_blocks_0_attn_to_k..., you already know why this node exists. SimpleTuner's Flux 2 builds fuse the attention projections into to_qkv_mlp_proj layers, which renames every LoRA key relative to what the normal Flux nodes expect. The keys don't match, nothing applies, and you get a silently useless generation. SimpleTunerFlux2LoRALoader is the fix: it's the node that actually applies SimpleTuner-trained Flux 2 LoRAs, using SimpleTuner's own pipeline underneath.

Where it sits in the workflow

It's the middle of a three-node chain:

[Load Flux 2 Pipeline] → [Load LoRA] → [Sample] → [Preview Image]

The whole pack speaks one custom type, ST_FLUX2_PIPELINE. The PipelineLoader hands you that object, this node attaches an adapter to it and passes the same pipeline out the other end, and the Sampler finally consumes it. You wire the loader's pipeline output into the sampler's pipeline input.

How it actually works

Under the hood it's diffusers/PEFT, not a key-remapping hack. The node calls pipeline.load_lora_weights(path, adapter_name=...) on SimpleTuner's Flux2Pipeline, then set_adapters([adapter_name], adapter_weights=[lora_scale]). Because the pipeline itself understands the fused architecture, the LoRA lands on the right tensors instead of being silently dropped.

The inputs that matter:

• lora_name - a dropdown that enumerates SimpleTuner's own output tree (SimpleTuner/output/<project>/checkpoint-<step>/pytorch_lora_weights.safetensors) plus everything in ComfyUI/models/loras/. Set it to none to skip loading entirely and pass the pipeline through.
• lora_scale - 0.0 to 2.0, default 1.0, in 0.05 steps. For Flux-era LoRAs, 1.0 is often too strong; 0.5–0.8 is a common starting range.
• lora_path_override - an optional absolute path if the dropdown can't see your file. Anything in here beats the dropdown.
• adapter_name - default "default". This is the PEFT adapter identity, and it matters for the Unloader: to remove a specific adapter later, you have to know the name it was loaded under.

The output is the pipeline (ST_FLUX2_PIPELINE), ready for the sampler.

Installing the pack

ComfyUI Manager: search "ComfyUI-SimpleTunerFlux2" and install. Or by hand - note the --recursive, because the SimpleTuner engine ships as a git submodule:

cd ComfyUI/custom_nodes
git clone --recursive https://github.com/flowers6421/ComfyUI-SimpleTunerFlux2.git
cd ComfyUI-SimpleTunerFlux2
./install.sh          # Linux/macOS
# python install.py   # Windows

The install script pulls SimpleTuner's dependencies (transformers, diffusers≥0.28, peft≥0.10, accelerate) plus the pack's own requirements.txt, and then restarts ComfyUI. This is a heavy stack, and the pack itself needs a model that can actually run Flux 2 - realistically 24GB+ of VRAM.

Where people get burned

• LoRA does nothing. Most often the file never loaded - check the dropdown isn't on none, and if you used lora_path_override, confirm the path resolves. A LoRA that does load but shows no effect is usually trained for a different Flux 2 variant (4B vs 9B LoRAs are not interchangeable).
• Architecture mismatch error. If you get a ValueError mentioning "Target modules ... not found", the pack's loader adds its own hint: the LoRA was probably trained on a different architecture, or the base model wasn't loaded through SimpleTuner's Flux2Pipeline. A Flux 1 LoRA will not apply here.
• Reusing the same adapter name. Loading a second LoRA under the same adapter_name can collide. Change the name, or run the Unloader first.

This is a niche pack for a niche workflow - you're only here because you trained with SimpleTuner. But when that's your situation, this is the node that makes the LoRA show up at all.