sgl-project/sglang · error · ValueError

Failed to load LoRA adapter {lora_ref.lora_name} as a pinned

Error message

Failed to load LoRA adapter {lora_ref.lora_name} as a pinned adapter. It is not allowed to pin all slots in the LoRA memory pool to avoid starvation for unpinned adapters and base models. Please increase your `--max-loras-per-batch` or load it as unpinned LoRA adapters.

What it means

Raised when loading a pinned LoRA adapter would occupy every slot in the LoRA memory pool. Pinned adapters permanently hold pool slots; the guard requires num_pinned_loras < max_loras_per_batch - 1 so at least one slot stays free for unpinned adapters and base-model requests, preventing starvation.

Source

Thrown at python/sglang/srt/lora/lora_manager.py:314

            if lora_ref.lora_path == existing_lora_ref.lora_path:
                logger.warning(
                    f"{lora_ref.lora_path} is already loaded with name: {existing_lora_ref.lora_name}, "
                    f"but another copy is being loaded with name: {lora_ref.lora_name}"
                )

        # Check if the LoRA adapter shape is compatible with the current LoRA memory pool configuration.
        memory_pool = getattr(self, "memory_pool", None)
        incompatible = memory_pool and not memory_pool.can_support(lora_config)
        if incompatible:
            raise ValueError(
                f"LoRA adapter {lora_ref.lora_name} with rank {lora_config.r} is incompatible with the current "
                "LoRA memory pool configuration. Please ensure that the LoRA adapter's rank is within the configured "
                "`--max-lora-rank` and that the target modules are included in `--lora-target-modules`."
            )

        # Ensure pinned LoRA adapters does not exceed maximal limit or cause starvation.
        if lora_ref.pinned and self.num_pinned_loras >= self.max_loras_per_batch - 1:
            raise ValueError(
                f"Failed to load LoRA adapter {lora_ref.lora_name} as a pinned adapter. It is not allowed to pin all slots "
                "in the LoRA memory pool to avoid starvation for unpinned adapters and base models. Please increase your "
                "`--max-loras-per-batch` or load it as unpinned LoRA adapters."
            )

    def unload_lora_adapter(self, lora_ref: LoRARef) -> LoRAUpdateOutput:
        logger.info(
            f"LoRA adapter unloading starts: {lora_ref}. "
            f"avail mem={get_available_gpu_memory(self.device.type, self.device.index):.2f} GB"
        )
        result = self._unload_lora_adapter(lora_ref)
        logger.info(
            f"LoRA adapter unloading completes: {lora_ref}. "
            f"avail mem={get_available_gpu_memory(self.device.type, self.device.index):.2f} GB"
        )
        return result

    def _unload_lora_adapter(self, lora_ref: LoRARef) -> LoRAUpdateOutput:

View on GitHub (pinned to 0132848349)

Solutions

1. Increase --max-loras-per-batch so pinned adapters leave a free slot
2. Load the adapter as unpinned instead of pinned
3. Unpin/unload an existing pinned adapter before pinning the new one

Example fix

# before
--enable-lora --max-loras-per-batch 2  # pin 2nd adapter fails
# after
--enable-lora --max-loras-per-batch 4

if lora_ref.pinned:
    assert manager.num_pinned_loras < manager.max_loras_per_batch - 1, "no slot left for another pinned LoRA"

When it happens

Trigger: Loading a LoRARef with pinned=True when self.num_pinned_loras already equals max_loras_per_batch - 1 (set by --max-lloras-per-batch / --max-loras-per-batch).

Common situations: Pinning several hot adapters at startup and then pinning one more, filling all slots allowed by a small --max-loras-per-batch value.

Related errors

• LoRA adapter {lora_ref.lora_name} with rank {lora_config.r}
• {selection_error}{component_suffix}
• Cosmos3CausalAttention requires num_attention_heads divisibl
• VLA action expert should not share the prefix TP layout. Use
• PEFT adapter_config.json must contain a JSON object

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/d673cb5114484b9b. Report an issue: GitHub.