sgl-project/sglang · error · ValueError

conflicting safetensors LoRA alpha metadata: {declared}

Error message

conflicting safetensors LoRA alpha metadata: {declared}

What it means

When multiple alpha-like metadata keys in the safetensors header parse successfully but disagree (e.g. 'lora_alpha': 16 and 'ss_network_alpha': 8), _load_safetensors_lora_alpha raises rather than guessing. The declared list of (key, value) pairs is included in the message. This guards against silently applying the wrong LoRA scale.

Source

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

        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):
        raise ValueError("PEFT adapter_config.json must contain a JSON object")
    metadata_alpha = _load_safetensors_lora_alpha(weight_path)
    config_alpha = get_peft_lora_alpha(config)
    if (
        metadata_alpha is not None
        and config_alpha is not None
        and metadata_alpha != config_alpha
    ):

View on GitHub (pinned to 0132848349)

Solutions

1. Open the file's metadata and pick the correct alpha (usually the PEFT 'lora_alpha' if loading as PEFT)
2. Remove or reconcile the conflicting key so all alpha keys agree
3. Re-save the safetensors with a single canonical alpha key

Example fix

# before: metadata {'lora_alpha': '16', 'ss_network_alpha': '8'}
# after: metadata {'lora_alpha': '16', 'ss_network_alpha': '16'}

with safe_open(path, framework="pt") as f:
    md = f.metadata() or {}
alphas = {int(float(v)) for k, v in md.items() if "alpha" in k.lower()}
assert len(alphas) <= 1, f"conflicting alphas in metadata: {alphas}"

When it happens

Trigger: An adapter file carrying two or more recognized alpha metadata keys with different positive-integer values, loaded via load_peft_config / load_lora_adapter.

Common situations: Adapters converted between kohya (ss_network_alpha) and PEFT (lora_alpha) conventions where one key was updated but not the other; merging metadata from multiple sources when packaging an adapter.

Related errors

• safetensors metadata {key!r} must be a positive integer
• adapter_config.json lora_alpha conflicts with safetensors me
• Native diffusion LoRA loading requires a safetensors file, g
• {name} must have dtype torch.int32
• {name} must be on the same device as block sparse tensors

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