{"record":{"id":"f931ae427dd07351","repo":"sgl-project/sglang","slug":"safetensors-metadata-key-r-must-be-a-positive-in","errorCode":null,"errorMessage":"safetensors metadata {key!r} must be a positive integer","messagePattern":"safetensors metadata (.+?) must be a positive integer","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py","lineNumber":64,"sourceCode":"    return len(ranks) == 1\n\n\ndef _load_safetensors_lora_alpha(weight_path: str) -> int | None:\n    if Path(weight_path).suffix.lower() != \".safetensors\":\n        return None\n    with safe_open(weight_path, framework=\"pt\", device=\"cpu\") as file:\n        metadata = file.metadata() or {}\n        if not _has_unambiguous_global_alpha(file):\n            return None\n    declared = []\n    for key in _SAFETENSORS_ALPHA_KEYS:\n        value = metadata.get(key)\n        if value is None:\n            continue\n        try:\n            numeric = float(value)\n        except (TypeError, ValueError) as error:\n            raise ValueError(\n                f\"safetensors metadata {key!r} must be a positive integer\"\n            ) from error\n        if not math.isfinite(numeric) or numeric <= 0 or not numeric.is_integer():\n            raise ValueError(f\"safetensors metadata {key!r} must be a positive integer\")\n        declared.append((key, int(numeric)))\n    values = {value for _, value in declared}\n    if len(values) > 1:\n        raise ValueError(f\"conflicting safetensors LoRA alpha metadata: {declared}\")\n    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):","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py#L46-L82","documentation":"_load_safetensors_lora_alpha reads LoRA alpha from safetensors file metadata; if a candidate key's value cannot be parsed as a float (TypeError/ValueError), this ValueError is raised with the parse error chained. It fails closed because an unparseable alpha would silently produce wrong LoRA scaling.","triggerScenarios":"Loading a LoRA adapter whose .safetensors header metadata contains an alpha-like key with a non-numeric value (e.g. 'lora_alpha': 'auto' or '') via load_peft_config / load_lora_adapter.","commonSituations":"Hand-edited safetensors metadata, adapters exported by third-party tools (kohya, ComfyUI scripts) that write metadata values as strings with stray characters, or corrupted downloads.","solutions":["Inspect the safetensors header metadata (safetensors.safe_open(...).metadata()) and fix or remove the offending alpha key","Re-export the adapter from the original training framework so metadata is written canonically","If the metadata is bogus, delete the alpha key and supply lora_alpha in adapter_config.json instead"],"exampleFix":"# before: metadata {'lora_alpha': 'auto'}\n# after: re-save with numeric metadata\nfrom safetensors.torch import save_file\nsave_file(tensors, 'adapter_model.safetensors', metadata={'lora_alpha': '16'})","handlingStrategy":"validation","validationCode":"from safetensors import safe_open\nwith safe_open(path, framework=\"pt\") as f:\n    md = f.metadata() or {}\nfor k, v in md.items():\n    if \"alpha\" in k.lower():\n        float(v)  # raises here first with a clear context if unparseable","typeGuard":"def has_parseable_alpha(md: dict) -> bool:\n    return all(\n        \"alpha\" not in k.lower() or _is_pos_int(v)\n        for k, v in (md or {}).items()\n    )","tryCatchPattern":"try:\n    cfg = load_peft_config(path)\nexcept ValueError as e:\n    if \"must be a positive integer\" in str(e):\n        fix_or_strip_safetensors_alpha(path)\n    raise","preventionTips":["Only load adapters exported by canonical tooling (PEFT)","Verify metadata keys after any manual checkpoint surgery"],"tags":["lora","safetensors","metadata","peft"],"backgroundTag":"invalid-model-metadata","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}