sgl-project/sglang · error · ValueError

conflicting safetensors LoRA alpha metadata

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.

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

• adapter_config.json lora_alpha conflicts with safetensors…
• safetensors metadata
• Native diffusion LoRA loading requires a safetensors file…
• Adapter not found in the pipeline. Please provide lora_path…
• Both dtype and regex are set. Only dtype will be used. dtype

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

Appendix: 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)