sgl-project/sglang · error · ValueError

Invalid --warmup-mode {self.warmup_mode!r}; expected one of

Error message

Invalid --warmup-mode {self.warmup_mode!r}; expected one of {WARMUP_MODES}.

What it means

--warmup-mode must be one of the WARMUP_MODES constants (e.g. 'off', 'server', ...) when explicitly provided. The check runs during argument adjustment (_adjust_warmup), before any warmup behavior is configured.

Source

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

    ) -> tuple[AttentionBackendEnum | None, str | None]:
        for component_name in component_names:
            if component_name is None:
                continue
            key = component_name.replace("-", "_")
            fallback_keys = [key]
            if key.endswith("_2"):
                # Secondary two-stage components inherit the base component
                # backend unless explicitly overridden.
                fallback_keys.append(key[:-2])
            for backend_key in fallback_keys:
                backend = self.component_attention_backends.get(backend_key)
                if backend is not None:
                    return AttentionBackendEnum[backend.upper()], backend_key
        return None, None

    def _adjust_warmup(self):
        if self.warmup_mode is not None and self.warmup_mode not in WARMUP_MODES:
            raise ValueError(
                f"Invalid --warmup-mode {self.warmup_mode!r}; "
                f"expected one of {WARMUP_MODES}."
            )
        if self.warmup_num_frames is not None and self.warmup_num_frames <= 0:
            raise ValueError("--warmup-num-frames must be a positive integer.")

        if self.enable_torch_compile and self.warmup_mode is None:
            self.warmup_mode = "server"
            logger.info(
                "Automatically enabled server warmup for torch.compile so first "
                "real requests do not pay compile latency. Set --warmup-mode off "
                "to disable this behavior."
            )

        # Explicit warmup shapes need a request path unless an existing server
        # default already supplies the synthetic startup request.
        if (
            self.warmup_resolutions is not None or self.warmup_num_frames is not None

View on GitHub (pinned to 0132848349)

Solutions

1. Check WARMUP_MODES in this version's server_args module and use an exact value
2. Omit --warmup-mode to take the default (auto 'server' when torch.compile is on)
3. Fix typos/casing per the supported set

Example fix

# before
--warmup-mode none
# after
--warmup-mode off

from sglang.multimodal_gen.runtime.server_args.server_args import WARMUP_MODES
assert warmup_mode is None or warmup_mode in WARMUP_MODES

def is_valid_warmup_mode(m) -> bool:
    return m is None or m in WARMUP_MODES

When it happens

Trigger: Passing --warmup-mode none or --warmup-mode full when the valid set is e.g. {'off','server',...}.

Common situations: Version changes adding/renaming warmup modes; guessing mode names; copying flags from another deployment with different supported modes.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• --warmup-num-frames must be a positive integer.
• {option} must use component=value entries
• component_attention_backends must use component=backend entr
• 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/3a0aa825090afc1a. Report an issue: GitHub.