sgl-project/sglang · error · ValueError

Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of

Error message

Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of {LTX2_TWO_STAGE_DEVICE_MODE_CHOICES}.

What it means

_adjust_ltx2_two_stage_device_mode normalizes ltx2_two_stage_device_mode and rejects any value outside LTX2_TWO_STAGE_DEVICE_MODES. The error prints the allowed choices tuple.

Source

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

    def _adjust_ltx2_two_stage_device_mode(self):
        if not self._is_ltx23_two_stage_pipeline():
            return

        mode = self.ltx2_two_stage_device_mode
        env_mode = None
        if mode is None:
            env_mode = os.getenv("SGLANG_LTX2_TWO_STAGE_DEVICE_MODE")
            mode = (
                _normalize_ltx2_two_stage_device_mode(env_mode)
                if env_mode
                else self._resolve_default_ltx2_two_stage_device_mode()
            )
        else:
            mode = _normalize_ltx2_two_stage_device_mode(mode)

        if mode not in LTX2_TWO_STAGE_DEVICE_MODES:
            raise ValueError(
                f"Invalid ltx2_two_stage_device_mode={mode!r}. "
                f"Expected one of {LTX2_TWO_STAGE_DEVICE_MODE_CHOICES}."
            )

        explicit_nonresident_dits = {
            component_name: residency_mode
            for component_name in ("transformer", "transformer_2")
            if (residency_mode := self.explicit_residency_mode(component_name))
            in (COMPONENT_OFFLOAD, LAYERWISE_OFFLOAD)
        }
        if mode == "resident" and explicit_nonresident_dits:
            configured = ", ".join(
                f"{name}={residency_mode}"
                for name, residency_mode in explicit_nonresident_dits.items()
            )
            if self.is_arg_explicitly_set("ltx2_two_stage_device_mode") or env_mode:
                raise ValueError(
                    "ltx2_two_stage_device_mode=resident conflicts with explicit "

View on GitHub (pinned to 0132848349)

Solutions

Use one of the values listed in LTX2_TWO_STAGE_DEVICE_MODE_CHOICES (check the constant near the top of server_args.py)
Omit the option to get the auto-resolved default via _resolve_default_ltx2_two_stage_device_mode

Example fix

# before
ServerArgs(..., ltx2_two_stage_device_mode="cpu-offload")
# after
ServerArgs(..., ltx2_two_stage_device_mode="original")

Defensive patterns

Strategy: validation

Validate before calling

from sglang...server_args import LTX2_TWO_STAGE_DEVICE_MODES
if mode not in LTX2_TWO_STAGE_DEVICE_MODES:
    raise SystemExit(f'bad ltx2_two_stage_device_mode {mode!r}; use {LTX2_TWO_STAGE_DEVICE_MODES}')

Type guard

def is_valid_ltx2_mode(m) -> bool:
    return m in LTX2_TWO_STAGE_DEVICE_MODES

Prevention

Pin the allowed choices from the installed version's constants, not docs
Prefer omitting the option to use the auto default

When it happens

Trigger: Passing an unrecognized mode string such as 'gpu-gpu' or a typo like 'offloaded'; env-var or programmatic override with a value not in LTX2_TWO_STAGE_DEVICE_MODES.

Common situations: New/renamed modes after upgrading; hand-written YAML with invented mode names; case errors are handled by the normalizer, so failures are genuine value typos.

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

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