{"record":{"id":"b35ec79cedd828ce","repo":"sgl-project/sglang","slug":"failed-to-load-lora-adapter-lora-ref-lora-name","errorCode":null,"errorMessage":"Failed to load LoRA adapter {lora_ref.lora_name}: {result.error_message}","messagePattern":"Failed to load LoRA adapter (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/lora/lora_manager.py","lineNumber":612,"sourceCode":"\n    def init_lora_adapters(self, lora_paths: Optional[List[LoRARef]] = None):\n        # Configs of all active LoRA adapters, indexed by LoRA ID.\n        self.configs: Dict[str, LoRAConfig] = {}\n\n        # LoRA adapter weights cached in CPU memory, indexed by LoRA ID.\n        self.loras: Dict[str, LoRAAdapter] = {}\n\n        # Mapping from LoRA ID to LoRARef object.\n        self.lora_refs: Dict[str, LoRARef] = {}\n\n        # Count of pinned LoRA adapters.\n        self.num_pinned_loras: int = 0\n\n        if lora_paths:\n            for lora_ref in lora_paths:\n                result = self._load_lora_adapter(lora_ref)\n                if not result.success:\n                    raise RuntimeError(\n                        f\"Failed to load LoRA adapter {lora_ref.lora_name}: {result.error_message}\"\n                    )\n\n    def _detect_shared_outer_loras(self) -> bool:\n        \"\"\"Auto-detect shared outer LoRA format from loaded adapter weights.\n\n        MoE adapters with shared outer experts store 3D tensors where\n        dim[0]=1 indicates weights shared across all experts, while\n        dim[0]=num_experts indicates per-expert weights.\n        Returns True if gate_up lora_A has expert_dim=1 (shared).\n\n        All loaded adapters that expose a 3D gate_up lora_A must agree;\n        mixed formats raise RuntimeError.\n        \"\"\"\n        shared_outer: Optional[bool] = None\n        for adapter_id, adapter in self.loras.items():\n            for layer in adapter.layers:\n                for name, weight in layer.weights.items():","sourceCodeStart":594,"sourceCodeEnd":630,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/lora/lora_manager.py#L594-L630","documentation":"Raised during LoRAManager.init_lora_adapters (called from init_state at startup) when an adapter listed in startup lora_paths fails to load and the internal _load_lora_adapter result reports success=False. It wraps the underlying error_message from the load attempt (weight conversion, file IO, config parse, etc.).","triggerScenarios":"Passing --lora-paths (or the equivalent lora_paths list) at server startup where at least one path is invalid, missing adapter_config.json/weights, or fails CUDA-side weight preparation, making result.success false.","commonSituations":"Typo in the adapter path in server args, an adapter saved in an unsupported format (DoRA, non-PEFT layout), or an OOM/corruption during weight loading at startup.","solutions":["Check the wrapped result.error_message in the traceback to identify the root cause","Verify the adapter path exists and contains a valid PEFT adapter (adapter_config.json + safetensors)","Fix or remove the offending entry from --lora-paths and restart","Confirm the adapter is plain LoRA (not DoRA) and its rank/targets match server flags"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import os\nfor name, path in lora_paths:\n    assert os.path.isdir(path) and os.path.exists(os.path.join(path, 'adapter_config.json')), f\"bad lora path: {path}\"","typeGuard":null,"tryCatchPattern":"try:\n    manager.init_lora_adapters(lora_paths)\nexcept RuntimeError as e:\n    log.error(\"startup LoRA load failed: %s\", e)  # e carries the inner error_message\n    raise SystemExit(1)","preventionTips":["Validate every --lora-paths entry exists locally on all workers","Test-load new adapters on a staging server before production startup","Keep adapters in a stable PEFT format"],"tags":["lora","startup","load-failure","sglang"],"backgroundTag":"dependency-load-failure","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}