sgl-project/sglang · error · ValueError

--warmup-num-frames must be a positive integer.

Error message

--warmup-num-frames must be a positive integer.

What it means

--warmup-num-frames, when provided, must be a positive integer (> 0). Zero or negative values are rejected in _adjust_warmup because warmup must run at least one frame.

Source

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

            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
        ) and self.warmup_mode in (None, "off"):
            self.warmup_mode = "request"

        # BCG captures every graph during a synthetic warmup forward at startup
        # so serving never records a fresh graph.

View on GitHub (pinned to 0132848349)

Solutions

1. Use --warmup-mode off to disable warmup entirely
2. Set a positive value, e.g. --warmup-num-frames 4
3. Check config templates that default this field to 0

Example fix

# before
--warmup-mode server --warmup-num-frames 0
# after
--warmup-mode off

assert warmup_num_frames is None or warmup_num_frames > 0

def valid_frame_count(n) -> bool:
    return n is None or (isinstance(n, int) and n > 0)

When it happens

Trigger: Passing --warmup-num-frames 0 (sometimes intended as 'disable') or a negative number.

Common situations: Trying to disable warmup by setting frames to 0 instead of --warmup-mode off; env-var or config defaulting to 0.

Related errors

• Invalid --warmup-mode {self.warmup_mode!r}; expected one of
• {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/3687deec70850c5a. Report an issue: GitHub.