sgl-project/sglang · error · ValueError

safetensors metadata {key!r} must be a positive integer

Error message

safetensors metadata {key!r} must be a positive integer

What it means

_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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py:64

    return len(ranks) == 1


def _load_safetensors_lora_alpha(weight_path: str) -> int | None:
    if Path(weight_path).suffix.lower() != ".safetensors":
        return None
    with safe_open(weight_path, framework="pt", device="cpu") as file:
        metadata = file.metadata() or {}
        if not _has_unambiguous_global_alpha(file):
            return None
    declared = []
    for key in _SAFETENSORS_ALPHA_KEYS:
        value = metadata.get(key)
        if value is None:
            continue
        try:
            numeric = float(value)
        except (TypeError, ValueError) as error:
            raise ValueError(
                f"safetensors metadata {key!r} must be a positive integer"
            ) from error
        if not math.isfinite(numeric) or numeric <= 0 or not numeric.is_integer():
            raise ValueError(f"safetensors metadata {key!r} must be a positive integer")
        declared.append((key, int(numeric)))
    values = {value for _, value in declared}
    if len(values) > 1:
        raise ValueError(f"conflicting safetensors LoRA alpha metadata: {declared}")
    return declared[0][1] if declared else None


def load_peft_config(weight_path: str) -> dict[str, Any]:
    path = Path(weight_path).with_name("adapter_config.json")
    config = {}
    if path.is_file():
        with path.open(encoding="utf-8") as file:
            config = json.load(file)
    if not isinstance(config, dict):

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect the safetensors header metadata (safetensors.safe_open(...).metadata()) and fix or remove the offending alpha key
2. Re-export the adapter from the original training framework so metadata is written canonically
3. If the metadata is bogus, delete the alpha key and supply lora_alpha in adapter_config.json instead

Example fix

# before: metadata {'lora_alpha': 'auto'}
# after: re-save with numeric metadata
from safetensors.torch import save_file
save_file(tensors, 'adapter_model.safetensors', metadata={'lora_alpha': '16'})

from safetensors import safe_open
with safe_open(path, framework="pt") as f:
    md = f.metadata() or {}
for k, v in md.items():
    if "alpha" in k.lower():
        float(v)  # raises here first with a clear context if unparseable

def has_parseable_alpha(md: dict) -> bool:
    return all(
        "alpha" not in k.lower() or _is_pos_int(v)
        for k, v in (md or {}).items()
    )

try:
    cfg = load_peft_config(path)
except ValueError as e:
    if "must be a positive integer" in str(e):
        fix_or_strip_safetensors_alpha(path)
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• conflicting safetensors LoRA alpha metadata: {declared}
• adapter_config.json lora_alpha conflicts with safetensors me
• PEFT adapter_config.json must contain a JSON object
• PEFT lora_alpha must be a positive integer
• Native diffusion LoRA loading requires a safetensors file, g

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