What causes "Failed to apply LoRA: {exc}" in unslothai/unsloth?

Read the chained original exception (`__cause__`) -- it names the real failure (shape mismatch, corrupt file, bad key).

unslothai/unsloth · error · ValueError

Failed to apply LoRA: {exc}

Error message

Failed to apply LoRA: {exc}

What it means

Catch-all wrapper around the actual diffusers LoRA application sequence (`unload_lora_weights`, `load_lora_weights` per adapter, `set_adapters` with weights). Any exception from diffusers during loading or activation is cleaned up after -- the pipe's LoRA weights are unloaded (best-effort) and `pipe._unsloth_loras` reset to empty -- then re-raised as a clean ValueError with the underlying exception chained. This guarantees the pipeline is left in a coherent, adapter-free state rather than half-loaded.

Source

Thrown at studio/backend/core/inference/diffusion.py:5081

        )
        uniq = list(desired)
        if desired == current:
            return
        try:
            if current:
                pipe.unload_lora_weights()
            for name, path, _weight in uniq:
                pipe.load_lora_weights(path, adapter_name = name)
            pipe.set_adapters(
                [name for name, _p, _w in uniq], adapter_weights = [w for _n, _p, w in uniq]
            )
        except Exception as exc:  # noqa: BLE001 -- surface as a clean 400
            try:
                pipe.unload_lora_weights()
            except Exception:  # noqa: BLE001
                pass
            pipe._unsloth_loras = ()
            raise ValueError(f"Failed to apply LoRA: {exc}") from exc
        pipe._unsloth_loras = desired

    def _adjust_baked_loras(
        self,
        state: Any,
        pipe: Any,
        specs: list[tuple[str, float]],
        current: tuple,
        quant_baked: bool,
        cancel: threading.Event,
    ) -> None:
        """Generation-time LoRA handling for a torchao-quantized pipe.

        The adapters (if any) were baked at load time, before quantize_ + compile, so the
        module topology is immutable here. Allowed without a reload: weight tweaks on the
        baked set and disabling everything (scale 0 reproduces the quantized base exactly;
        set_adapters is value-level, so torch.compile guards absorb it). Anything that would
        change topology (adding adapters to a bake-less load, or a different adapter set)

View on GitHub (pinned to 203007d190)

Solutions

Read the chained original exception (`__cause__`) -- it names the real failure (shape mismatch, corrupt file, bad key).
Verify the LoRA was trained for the loaded model family/base checkpoint and re-download the adapter.
Retry without the failing adapter to isolate which one in the set breaks.
Upgrade diffusers to match the adapter's serialization format.

Defensive patterns

Strategy: try-catch

Validate before calling

# Sanity-check adapter files before generate
for path in adapter_paths:
    with safe_open(path, framework="pt") as f:  # safetensors
        keys = list(f.keys())
    assert any(k.startswith(arch_prefix) for k in keys), f"{path} not for this family"

Type guard

def adapter_parses(path: str) -> bool:
    try:
        with safe_open(path, framework="pt"):
            return True
    except Exception:
        return False

Try / catch

try:
    diffusion.generate(prompt=p, loras=loras)
except ValueError as e:
    if str(e).startswith("Failed to apply LoRA:"):
        cause = e.__cause__  # real diffusers failure: shape mismatch, corrupt file, bad keys
        log.warning("LoRA apply failed: %s", cause)
        return diffusion.generate(prompt=p, loras=[])  # adapter-free fallback
    raise

Prevention

Always inspect the chained __cause__; the wrapper hides the real reason in its text.
Verify adapters were trained against the same base architecture before queuing them.
The pipeline self-cleans (unload_lora_weights + reset) on failure -- safe to continue without adapters.

When it happens

Trigger: An adapter file that fails to parse in `load_lora_weights` (corrupt safetensors, mismatched layer shapes for this family), an invalid adapter_name collision handling, or `set_adapters` rejecting the weights list -- any Exception inside the try block triggers the cleanup and the wrapped raise.

Common situations: LoRA trained for a different base model architecture (key mismatch on load); truncated/corrupt adapter downloads; floating adapter weight lists whose length differs from the adapter list; version drift between diffusers and the adapter's serialization format.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/60a5d486b74036ad. Report an issue: GitHub.