What causes "Missing LoRA layer: '{src_key}'." in invoke-ai/InvokeAI?

Pass allow_missing_keys=True to skip non-matching qkv sub-layers if partial application is acceptable.

invoke-ai/InvokeAI · error · ValueError

Missing LoRA layer: '{src_key}'.

Error message

Missing LoRA layer: '{src_key}'.

What it means

add_qkv_lora_layer_if_present merges per-layer LoRA sub-layers into a single MergedLayerPatch targeting the model's fused qkv weight. When a sub-layer's source key (src_key) cannot be found in the transformer state dict, the function raises ValueError('Missing LoRA layer: ...') unless allow_missing_keys is True. It guards against LoRAs written against a model whose qkv layout/shapes don't match the target model.

Source

Thrown at invokeai/backend/patches/lora_conversions/flux_diffusers_lora_conversion_utils.py:172

        # If none of the keys are present, return early.
        keys_present = [key in grouped_state_dict for key in src_keys]
        if not any(keys_present):
            return

        dim_0_offset = 0
        sub_layers: list[BaseLayerPatch] = []
        sub_layer_ranges: list[Range] = []
        for src_key, src_weight_shape in zip(src_keys, src_weight_shapes, strict=True):
            src_layer_dict = grouped_state_dict.pop(src_key, None)
            if src_layer_dict is not None:
                values = get_lora_layer_values(src_layer_dict)
                # assert values["lora_down.weight"].shape[1] == src_weight_shape[1]
                # assert values["lora_up.weight"].shape[0] == src_weight_shape[0]
                sub_layers.append(any_lora_layer_from_state_dict(values))
                sub_layer_ranges.append(Range(dim_0_offset, dim_0_offset + src_weight_shape[0]))
            else:
                if not allow_missing_keys:
                    raise ValueError(f"Missing LoRA layer: '{src_key}'.")

            dim_0_offset += src_weight_shape[0]

        layers[dst_qkv_key] = MergedLayerPatch(sub_layers, sub_layer_ranges)

    # time_text_embed.timestep_embedder -> time_in.
    add_lora_layer_if_present("time_text_embed.timestep_embedder.linear_1", "time_in.in_layer")
    add_lora_layer_if_present("time_text_embed.timestep_embedder.linear_2", "time_in.out_layer")

    # time_text_embed.text_embedder -> vector_in.
    add_lora_layer_if_present("time_text_embed.text_embedder.linear_1", "vector_in.in_layer")
    add_lora_layer_if_present("time_text_embed.text_embedder.linear_2", "vector_in.out_layer")

    # time_text_embed.guidance_embedder -> guidance_in.
    add_lora_layer_if_present("time_text_embed.guidance_embedder.linear_1", "guidance_in")
    add_lora_layer_if_present("time_text_embed.guidance_embedder.linear_2", "guidance_in")

    # context_embedder -> txt_in.

View on GitHub (pinned to 0b6a024f2f)

Solutions

Pass allow_missing_keys=True to skip non-matching qkv sub-layers if partial application is acceptable.
Verify the LoRA and base checkpoint are the same FLUX variant; use a LoRA made for your exact model.
Inspect src_key and pre-check the model's state dict for it; drop or remap keys that don't exist before conversion.

Example fix

// before
layers = lora_layers_from_flux_diffusers_grouped_state_dict(sd)
// after
layers = lora_layers_from_flux_diffusers_grouped_state_dict(sd, allow_missing_keys=True)

Defensive patterns

Strategy: validation

Validate before calling

model_keys = set(model_sd.keys())
missing = [k for k in lora_src_keys if k not in model_keys]
assert not missing, f"LoRA targets missing model keys: {missing}"

Try / catch

try:
    layers = lora_layers_from_flux_diffusers_grouped_state_dict(sd, model_sd)
except ValueError as e:
    logger.warning("Missing qkv LoRA layer, retrying with allow_missing_keys: %s", e)
    layers = lora_layers_from_flux_diffusers_grouped_state_dict(sd, model_sd, allow_missing_keys=True)

Prevention

Match LoRA variant to the exact base checkpoint (dev vs schnell vs other FLUX).
Pre-check that LoRA source keys exist in the model state dict.
Use allow_missing_keys=True when partial application is acceptable.

When it happens

Trigger: Calling lora_layers_from_flux_diffusers_grouped_state_dict with allow_missing_keys=False (the default) and a grouped diffusers FLUX LoRA whose qkv sub-layer keys don't align with the model's qkv rows (e.g. LoRA trained on a differently-shaped/text-encoder-augmented FLUX variant).

Common situations: Mixing FLUX.1-dev LoRAs with FLUX.1-schnell or Flux variant models; LoRAs exported with extra or renamed attention projections; passing the wrong model path so source weight shapes differ.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/22b10a72fb2f86eb. Report an issue: GitHub.