sgl-project/sglang · error · ValueError

lora_alpha must be a positive integer

Error message

lora_alpha must be a positive integer

What it means

Validation in _validate_parameters: lora_alpha, when set, must be a positive integer (> 0). It is checked after scheduler/pipeline/offload validation and before parallelism checks.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:582

        self._adjust_warmup()
        self._adjust_network_ports()
        # adjust parallelism before attention backend
        self._adjust_parallelism()
        self._adjust_attention_backend()
        self._adjust_platform_specific()
        self._adjust_layerwise_offload_components()
        self._adjust_autocast()
        auto_tuner.finalize_auto_flags()
        self.adjust_pipeline_config()

    def _validate_parameters(self):
        """check consistency and raise errors for invalid configs"""
        self._validate_scheduler_rpc_timeout()
        self._validate_pipeline()
        self._validate_offload()
        self._validate_direct_gpu_weight_loading()
        if self.lora_alpha is not None and self.lora_alpha <= 0:
            raise ValueError("lora_alpha must be a positive integer")
        if not current_platform.is_cpu():
            self._validate_parallelism()
        self._validate_cfg_parallel()
        self._validate_batching()
        self._validate_breakable_cuda_graph()
        self.pipeline_config.validate_server_args(self)

    def _validate_scheduler_rpc_timeout(self) -> None:
        timeout = self.scheduler_rpc_timeout
        if timeout is None:
            return
        if (
            not isinstance(timeout, int)
            or isinstance(timeout, bool)
            or not 0 < timeout <= MAX_SCHEDULER_RPC_TIMEOUT_S
        ):
            raise ValueError(
                "scheduler_rpc_timeout must be None or an integer between "

View on GitHub (pinned to 0132848349)

Solutions

1. Set lora_alpha=None (or omit it) to disable LoRA
2. Use a positive integer such as 16 or 32 matching your LoRA training config

Example fix

# before
ServerArgs(..., lora_alpha=0)
# after
ServerArgs(..., lora_alpha=None)

if cfg.get('lora_alpha') is not None and (not isinstance(cfg['lora_alpha'], int) or cfg['lora_alpha'] <= 0):
    cfg['lora_alpha'] = None  # or fail fast with a clear config error

def valid_lora_alpha(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)

When it happens

Trigger: ServerArgs(dataclass) constructed with lora_alpha=0 or a negative value, then __post_init__ runs _validate_parameters. Also any path that passes a None-check but stores 0 (e.g. int(os.getenv(...)) defaulting to 0).

Common situations: Setting LoRA alpha to 0 intending 'disabled' instead of None; env var parsing that yields 0; copy-paste from a config where alpha was unset.

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

• Invalid LoRA merge mode: {merge_mode}. Valid modes: {LORA_ME
• Invalid target(s): {invalid_targets}. Valid targets: {self.V
• LoRA adapter '{first_adapter}' was requested, but LoRA is no
• SGLANG_GRPC_WORKER_THREADS ({cfg.grpc_worker_threads}) must
• --sidecar-args requires --sidecar.

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