sgl-project/sglang · error · ValueError

Invalid LoRA merge mode: {merge_mode}. Valid modes: {LORA_ME

Error message

Invalid LoRA merge mode: {merge_mode}. Valid modes: {LORA_MERGE_MODES}

What it means

Thrown by _resolve_lora_merge_mode when the resolved LoRA merge mode string is not one of LORA_MERGE_MODES (typically 'merge' or 'dynamic'). The mode is resolved from an explicit argument, or from the legacy merge_weights boolean, or falls back to server_args.lora_merge_mode — any typo in any of these triggers it.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/lora/pipeline.py:589

        module_name: str,
        lora_layers: dict[str, BaseLayerWithLoRA],
    ) -> bool:
        return self.is_lora_merged.get(
            module_name, False
        ) or self._has_active_unmerged_lora(lora_layers)

    def _resolve_lora_merge_mode(
        self,
        merge_weights: bool | None,
        merge_mode: str | None,
    ) -> str:
        if merge_mode is None:
            if merge_weights is not None:
                merge_mode = "merge" if merge_weights else "dynamic"
            else:
                merge_mode = self.server_args.lora_merge_mode
        if merge_mode not in LORA_MERGE_MODES:
            raise ValueError(
                f"Invalid LoRA merge mode: {merge_mode}. Valid modes: {LORA_MERGE_MODES}"
            )
        return merge_mode

    def _should_merge_lora_for_layers(
        self,
        module_name: str,
        lora_layers: dict[str, BaseLayerWithLoRA],
        merge_mode: str,
    ) -> bool:
        if merge_mode == "dynamic":
            return False
        uses_dtensor_weights = self._uses_dtensor_weights(lora_layers)
        if merge_mode == "auto":
            if uses_dtensor_weights:
                logger.info(
                    "Using dynamic LoRA for %s because FSDP-sharded weights would require a full-gather merge.",
                    module_name,

View on GitHub (pinned to 0132848349)

Solutions

1. Set merge_mode to a valid value from LORA_MERGE_MERGE modes: check `from sglang.multimodal_gen.runtime.pipelines_core.lora.pipeline import LORA_MERGE_MODES` — currently 'merge' or 'dynamic'
2. Fix server_args.lora_merge_mode in your launch config
3. If using legacy merge_weights, drop the merge_mode argument entirely

Example fix

# before
pipeline.set_lora(lora_paths=[p], lora_nicknames=['a'], merge_mode='merged')
# after
pipeline.set_lora(lora_paths=[p], lora_nicknames=['a'], merge_mode='merge')

from sglang.multimodal_gen.runtime.pipelines_core.lora.pipeline import LORA_MERGE_MODES
assert merge_mode in LORA_MERGE_MODES, f'{merge_mode} not in {LORA_MERGE_MODES}'

def is_valid_merge_mode(m: str) -> bool: return m in LORA_MERGE_MODES

When it happens

Trigger: Calling set_lora(merge_mode='merged') or configuring server_args.lora_merge_mode to an invalid string; also passing merge_weights plus an invalid merge_mode, since merge_mode takes precedence.

Common situations: Typos in pipeline config YAML/JSON for lora_merge_mode; upgrading to a version that renamed modes; passing merge_weights-style booleans where a string mode is expected.

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 target(s): {invalid_targets}. Valid targets: {self.V
• lora_alpha must be a positive integer
• bad compress_ratio {compress_ratio}
• The requested FlashAttention forward configuration exceeds S
• flashinfer_sparse_mla supports only GLM DSA with FP8 KV cach

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