unslothai/unsloth · error · ValueError

GGUF LoRA adapters are not supported on the diffusers engine

Error message

GGUF LoRA adapters are not supported on the diffusers engine ({', '.join(bad)}); use a .safetensors adapter, or the native engine.

What it means

Raised in `_resolve_lora_set` after `diffusion_lora.resolve_specs` resolves the requested LoRA specs: any adapter whose resolved format is not 'safetensors' (i.e. a .gguf LoRA) is rejected because diffusers' `load_lora_weights` accepts safetensors only. The offending adapter ids are joined into the message, and it is a ValueError so the API returns a clean 400 pointing at alternatives (.safetensors adapter or the native engine).

Source

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

        cancel: Optional[threading.Event] = None,
    ) -> tuple[tuple[str, str, float], ...]:
        """Resolve (id, weight) specs to a ``(name, path, weight)`` tuple set for diffusers.

        Shared by the generation-time apply path and the quant load-time bake so both produce
        IDENTICAL tuples for the same request (the no-op / weight-only comparisons depend on it).
        """
        from core.inference import diffusion_lora

        resolved = diffusion_lora.resolve_specs(
            specs,
            family = family,
            hf_token = hf_token,
            cancel_event = cancel,
        )
        # diffusers load_lora_weights takes safetensors only; reject a .gguf adapter as a clean 400.
        bad = [r.id for r in resolved if r.fmt != "safetensors"]
        if bad:
            raise ValueError(
                "GGUF LoRA adapters are not supported on the diffusers engine "
                f"({', '.join(bad)}); use a .safetensors adapter, or the native engine."
            )
        # Unique adapter names (diffusers requires distinct names; sanitized stems can collide).
        uniq: list[tuple[str, str, float]] = []
        seen: set[str] = set()
        for r in resolved:
            name = r.alias
            n = 1
            while name in seen:
                n += 1
                name = f"{r.alias}_{n}"
            seen.add(name)
            uniq.append((name, r.path, r.weight))
        return tuple(uniq)

    def _apply_loras(
        self, state: Any, loras: Optional[list[tuple[str, float]]], cancel: threading.Event

View on GitHub (pinned to 203007d190)

Solutions

1. Find or request a .safetensors build of the same LoRA adapter and use that id.
2. Convert the GGUF LoRA back to safetensors with an external tool, then reference the converted file.
3. Switch the job to the native engine (sd_cpp), which accepts GGUF adapters.

Example fix

# before
diffusion.generate(prompt="...", loras=[("quant-lora:gguf", 1.0)])
# after
diffusion.generate(prompt="...", loras=[("same-lora:safetensors", 1.0)])

# Resolve adapter format before generate
specs = diffusion_lora.resolve_specs(lora_specs, family=family)
if any(r.fmt != "safetensors" for r in resolved):
    raise ValueError("pick .safetensors adapters for the diffusers engine")

def all_safetensors(resolved: list) -> bool:
    """Every resolved LoRA spec is a safetensors adapter the diffusers engine can load."""
    return all(r.fmt == "safetensors" for r in resolved)

try:
    diffusion.generate(prompt=p, loras=loras)
except ValueError as e:
    if "GGUF LoRA adapters are not supported" in str(e):
        loras = [to_safetensors_equivalent(l) for l in loras]
        diffusion.generate(prompt=p, loras=loras)
    else:
        raise

When it happens

Trigger: Passing a `loras` spec list where at least one id resolves to a .gguf-format adapter (r.fmt != 'safetensors') while running on the diffusers engine; e.g. a GGUF-quantized LoRA from a Hub repo that only ships gguf artifacts.

Common situations: Users downloading GGUF LoRAs (common in the sd.cpp/llama.cpp ecosystem) and trying them in a diffusers-based studio; Hub repos that publish both formats with the GGUF first; mixing native-engine model packs into the diffusers engine.

Related errors

• a single-file checkpoint name is required for a '{kind}' loa
• a 'gguf' load requires a .gguf checkpoint name.
• a .gguf checkpoint needs model_kind 'gguf', not 'single_file
• '{gguf_filename}' is not a loadable single-file checkpoint (
• Local model path does not exist: {repo_id}

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