{"record":{"id":"6eace21f095de5d5","repo":"sgl-project/sglang","slug":"adapter-config-json-lora-alpha-conflicts-with-safe","errorCode":null,"errorMessage":"adapter_config.json lora_alpha conflicts with safetensors metadata: {config_alpha} != {metadata_alpha}","messagePattern":"adapter_config\\.json lora_alpha conflicts with safetensors metadata: (.+?) != (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py","lineNumber":91,"sourceCode":"    return declared[0][1] if declared else None\n\n\ndef load_peft_config(weight_path: str) -> dict[str, Any]:\n    path = Path(weight_path).with_name(\"adapter_config.json\")\n    config = {}\n    if path.is_file():\n        with path.open(encoding=\"utf-8\") as file:\n            config = json.load(file)\n    if not isinstance(config, dict):\n        raise ValueError(\"PEFT adapter_config.json must contain a JSON object\")\n    metadata_alpha = _load_safetensors_lora_alpha(weight_path)\n    config_alpha = get_peft_lora_alpha(config)\n    if (\n        metadata_alpha is not None\n        and config_alpha is not None\n        and metadata_alpha != config_alpha\n    ):\n        raise ValueError(\n            \"adapter_config.json lora_alpha conflicts with safetensors metadata: \"\n            f\"{config_alpha} != {metadata_alpha}\"\n        )\n    if metadata_alpha is not None:\n        config.setdefault(\"lora_alpha\", metadata_alpha)\n    return config\n\n\ndef get_peft_lora_alpha(config: Mapping[str, Any]) -> int | None:\n    alpha = config.get(\"lora_alpha\")\n    if alpha is None:\n        return None\n    if (\n        isinstance(alpha, bool)\n        or not isinstance(alpha, (int, float))\n        or alpha <= 0\n        or isinstance(alpha, float)\n        and not alpha.is_integer()","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py#L73-L109","documentation":"load_peft_config cross-checks the LoRA alpha declared in adapter_config.json against the alpha found in the safetensors metadata. If both exist and differ, it raises this conflict error listing both values, refusing to guess which scale to apply (a wrong alpha silently ruins adapter quality).","triggerScenarios":"An adapter directory where adapter_config.json says lora_alpha=8 but the .safetensors header metadata says 16 (or another alpha-like key disagrees), loaded via load_lora_adapter.","commonSituations":"Manually editing adapter_config.json to retune alpha without re-saving the safetensors metadata; converting adapters between kohya and PEFT formats where alpha conventions differ; merging adapters.","solutions":["Decide the true alpha (usually from the training run) and make both sources agree","Either edit lora_alpha in adapter_config.json to match metadata, or re-save the safetensors metadata to match the config","If metadata is spurious, strip the alpha keys from safetensors metadata and keep only adapter_config.json"],"exampleFix":"# before: config lora_alpha=8, safetensors metadata lora_alpha='16'\n# after: both set to 16 (edit adapter_config.json or re-save metadata)","handlingStrategy":"validation","validationCode":"cfg_alpha = json.load(open(p/\"adapter_config.json\")).get(\"lora_alpha\")\nwith safe_open(str(p/\"adapter_model.safetensors\"), framework=\"pt\") as f:\n    md_alpha = (f.metadata() or {}).get(\"lora_alpha\")\nif cfg_alpha is not None and md_alpha is not None:\n    assert int(cfg_alpha) == int(float(md_alpha)), \"alpha mismatch across config and metadata\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When retuning alpha, update both adapter_config.json and safetensors metadata","Prefer a single source of truth: remove alpha from metadata or from config"],"tags":["lora","peft","metadata","conflict"],"backgroundTag":"conflicting-model-metadata","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}