{"record":{"id":"e7665b09390eff1b","repo":"sgl-project/sglang","slug":"lora-adapter-lora-ref-lora-name-with-rank-lora","errorCode":null,"errorMessage":"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`.","messagePattern":"LoRA adapter (.+?) with rank (.+?) 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`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/lora/lora_manager.py","lineNumber":306,"sourceCode":"\n        # Check if this LoRA adapter is already loaded\n        for existing_lora_ref in self.lora_refs.values():\n            if lora_ref.lora_name == existing_lora_ref.lora_name:\n                raise ValueError(\n                    f\"Failed to load LoRA adapter {lora_ref.lora_name} because it is already loaded\"\n                )\n\n            if lora_ref.lora_path == existing_lora_ref.lora_path:\n                logger.warning(\n                    f\"{lora_ref.lora_path} is already loaded with name: {existing_lora_ref.lora_name}, \"\n                    f\"but another copy is being loaded with name: {lora_ref.lora_name}\"\n                )\n\n        # Check if the LoRA adapter shape is compatible with the current LoRA memory pool configuration.\n        memory_pool = getattr(self, \"memory_pool\", None)\n        incompatible = memory_pool and not memory_pool.can_support(lora_config)\n        if incompatible:\n            raise ValueError(\n                f\"LoRA adapter {lora_ref.lora_name} with rank {lora_config.r} is incompatible with the current \"\n                \"LoRA memory pool configuration. Please ensure that the LoRA adapter's rank is within the configured \"\n                \"`--max-lora-rank` and that the target modules are included in `--lora-target-modules`.\"\n            )\n\n        # Ensure pinned LoRA adapters does not exceed maximal limit or cause starvation.\n        if lora_ref.pinned and self.num_pinned_loras >= self.max_loras_per_batch - 1:\n            raise ValueError(\n                f\"Failed to load LoRA adapter {lora_ref.lora_name} as a pinned adapter. It is not allowed to pin all slots \"\n                \"in the LoRA memory pool to avoid starvation for unpinned adapters and base models. Please increase your \"\n                \"`--max-loras-per-batch` or load it as unpinned LoRA adapters.\"\n            )\n\n    def unload_lora_adapter(self, lora_ref: LoRARef) -> LoRAUpdateOutput:\n        logger.info(\n            f\"LoRA adapter unloading starts: {lora_ref}. \"\n            f\"avail mem={get_available_gpu_memory(self.device.type, self.device.index):.2f} GB\"\n        )","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/lora/lora_manager.py#L288-L324","documentation":"Raised when a new LoRA adapter's configuration (rank, target modules) cannot be supported by the pre-allocated LoRA memory pool. SGLang pre-allocates LoRA buffer sizes at startup from --max-lora-rank and --lora-target-modules, so an adapter whose rank exceeds that or whose target modules fall outside the pool's supported set fails validation via memory_pool.can_support(lora_config).","triggerScenarios":"Loading a LoRA (via load API or startup lora_paths) whose PEFT config rank r > --max-lora-rank, or whose target modules are not covered by the pool built from --lora-target-modules.","commonSituations":"Trained an adapter with rank 128 but server started with default/lower --max-lora-rank (e.g. 16 or 64); adapter targets q_proj/k_proj but pool was configured only for gate_up_proj/down_proj.","solutions":["Restart the server with --max-lora-rank at least the adapter's rank (e.g. --max-lora-rank 128)","Add the adapter's target module suffixes to --lora-target-modules (or use 'all')","Retrain/export the adapter with a smaller rank that fits the current pool"],"exampleFix":"# before\npython -m sglang.launch_server --model ... --enable-lora --max-lora-rank 16\n# after\npython -m sglang.launch_server --model ... --enable-lora --max-lora-rank 128 --lora-target-modules 'all'","handlingStrategy":"validation","validationCode":"from peft import PeftConfig\ncfg = PeftConfig.from_pretrained(path)\nassert cfg.r <= server_args.max_lora_rank, f\"rank {cfg.r} exceeds --max-lora-rank\"\nassert set(cfg.target_modules) <= set(server_args.lora_target_modules)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set --max-lora-rank to the largest rank you plan to serve","Pre-validate adapter_config.json (r, target_modules) against server flags before loading","Use --lora-target-modules all when unsure"],"tags":["lora","memory-pool","rank","config","sglang"],"backgroundTag":"resource-capacity-exceeded","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}