sgl-project/sglang · error · ValueError

PEFT lora_alpha must be a positive integer

Error message

PEFT lora_alpha must be a positive integer

What it means

get_peft_lora_alpha validates the lora_alpha field of a PEFT config: it must be an int or float that is positive, finite-integral, and not a bool. Anything else (string '16', 0, negative, NaN, 16.5, True) raises. It returns int(alpha) on success and is used by load_peft_config, apply_peft_config, and load_lora_adapter, deliberately failing closed.

Source

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

            f"{config_alpha} != {metadata_alpha}"
        )
    if metadata_alpha is not None:
        config.setdefault("lora_alpha", metadata_alpha)
    return config


def get_peft_lora_alpha(config: Mapping[str, Any]) -> int | None:
    alpha = config.get("lora_alpha")
    if alpha is None:
        return None
    if (
        isinstance(alpha, bool)
        or not isinstance(alpha, (int, float))
        or alpha <= 0
        or isinstance(alpha, float)
        and not alpha.is_integer()
    ):
        raise ValueError("PEFT lora_alpha must be a positive integer")
    return int(alpha)


def normalize_peft_keys(
    state_dict: Mapping[str, torch.Tensor],
) -> dict[str, torch.Tensor]:
    """Remove a uniform PEFT model wrapper and named adapter slot."""
    prefix = next(
        (
            prefix
            for prefix in _WRAPPER_PREFIXES
            if state_dict and all(name.startswith(prefix) for name in state_dict)
        ),
        "",
    )
    normalized: dict[str, torch.Tensor] = {}
    slots = set()
    has_bare_weights = False

View on GitHub (pinned to 0132848349)

Solutions

1. Set lora_alpha to a positive integer in adapter_config.json / the config dict
2. If it comes from YAML/CLI, coerce to int before passing: int(config['lora_alpha'])
3. Re-run PEFT export so the config is written with a native int

Example fix

# before: { "lora_alpha": "16" }
# after:  { "lora_alpha": 16 }

alpha = config.get("lora_alpha")
if isinstance(alpha, str) and alpha.strip().isdigit():
    config["lora_alpha"] = alpha = int(alpha)
assert isinstance(alpha, int) and not isinstance(alpha, bool) and alpha > 0

def is_valid_peft_alpha(alpha) -> bool:
    if isinstance(alpha, bool):
        return False
    if isinstance(alpha, int):
        return alpha > 0
    return isinstance(alpha, float) and alpha > 0 and float(alpha).is_integer()

When it happens

Trigger: Passing or loading a PEFT config where lora_alpha is a string, boolean, non-positive number, or non-integer float; e.g. adapter_config.json with "lora_alpha": "16" or setting config['lora_alpha'] = True.

Common situations: Configs hand-edited or generated from YAML where numbers become strings; JSON with alpha as "16"; tests that probe invalid alpha; copying example configs that quote numbers.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• PEFT adapter_config.json must contain a JSON object
• LoRA batch_info must provide max_len or seg_lens.
• lora_nickname cannot be empty
• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head

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