{"record":{"id":"69e9613400d4cca2","repo":"sgl-project/sglang","slug":"peft-lora-alpha-must-be-a-positive-integer","errorCode":null,"errorMessage":"PEFT lora_alpha must be a positive integer","messagePattern":"PEFT lora_alpha 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":111,"sourceCode":"            f\"{config_alpha} != {metadata_alpha}\"\n        )\n    if metadata_alpha is not None:\n        config.setdefault(\"lora_alpha\", metadata_alpha)\n    return config\n\n\ndef get_peft_lora_alpha(config: Mapping[str, Any]) -> int | None:\n    alpha = config.get(\"lora_alpha\")\n    if alpha is None:\n        return None\n    if (\n        isinstance(alpha, bool)\n        or not isinstance(alpha, (int, float))\n        or alpha <= 0\n        or isinstance(alpha, float)\n        and not alpha.is_integer()\n    ):\n        raise ValueError(\"PEFT lora_alpha must be a positive integer\")\n    return int(alpha)\n\n\ndef normalize_peft_keys(\n    state_dict: Mapping[str, torch.Tensor],\n) -> dict[str, torch.Tensor]:\n    \"\"\"Remove a uniform PEFT model wrapper and named adapter slot.\"\"\"\n    prefix = next(\n        (\n            prefix\n            for prefix in _WRAPPER_PREFIXES\n            if state_dict and all(name.startswith(prefix) for name in state_dict)\n        ),\n        \"\",\n    )\n    normalized: dict[str, torch.Tensor] = {}\n    slots = set()\n    has_bare_weights = False","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/lora/peft_adapter.py#L93-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set lora_alpha to a positive integer in adapter_config.json / the config dict","If it comes from YAML/CLI, coerce to int before passing: int(config['lora_alpha'])","Re-run PEFT export so the config is written with a native int"],"exampleFix":"# before: { \"lora_alpha\": \"16\" }\n# after:  { \"lora_alpha\": 16 }","handlingStrategy":"type-guard","validationCode":"alpha = config.get(\"lora_alpha\")\nif isinstance(alpha, str) and alpha.strip().isdigit():\n    config[\"lora_alpha\"] = alpha = int(alpha)\nassert isinstance(alpha, int) and not isinstance(alpha, bool) and alpha > 0","typeGuard":"def is_valid_peft_alpha(alpha) -> bool:\n    if isinstance(alpha, bool):\n        return False\n    if isinstance(alpha, int):\n        return alpha > 0\n    return isinstance(alpha, float) and alpha > 0 and float(alpha).is_integer()","tryCatchPattern":null,"preventionTips":["Coerce YAML/CLI-sourced config values to int before building adapters","Never quote numeric fields when hand-editing JSON configs"],"tags":["lora","peft","validation","config"],"backgroundTag":"invalid-config-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}