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

Raised by LTX2TwoStageDeviceMode._resolve_mode when the requested two-stage device placement mode is not in VALID_MODES. Mode strings come from the argument or the LTX2_TWO_STAGE_DEVICE_MODE environment variable and are normalized before validation, so this fires only for genuinely unknown values.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py:577

        self.server_args = server_args
        self.mode = self._resolve_mode(server_args)
        self._active_phase: str | None = None
        self._strategy = self._build_strategy()

    @classmethod
    def _resolve_mode(cls, server_args: ServerArgs) -> str:
        mode = server_args.ltx2_two_stage_device_mode
        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 "original"
            )
        else:
            mode = _normalize_ltx2_two_stage_device_mode(mode)
        if mode not in cls.VALID_MODES:
            raise ValueError(
                f"Invalid ltx2_two_stage_device_mode={mode!r}. "
                f"Expected one of {LTX2_TWO_STAGE_DEVICE_MODE_CHOICES}."
            )
        return mode

    def _build_strategy(self) -> LTX2TwoStageResidencyStrategy:
        if self.mode == "resident":
            return LTX2ResidentResidencyStrategy(self)
        return LTX2OriginalResidencyStrategy(self)

    @property
    def strategy(self) -> ComponentResidencyStrategy:
        return self._strategy

    @property
    def should_use_premerged(self) -> bool:
        """Whether to keep a pre-merged stage-2 DiT for LTX-2.3 two-stage.

View on GitHub (pinned to 0132848349)

Solutions

Set the mode to one of LTX2_TWO_STAGE_DEVICE_MODE_CHOICES (e.g. 'original' or the documented alternates) — print that constant to see valid values for your version
Unset LTX2_TWO_STAGE_DEVICE_MODE if you want the default 'original' behavior
After upgrading sglang, re-check the choices constant for renamed modes

Example fix

# before
export LTX2_TWO_STAGE_DEVICE_MODE=orginal  # typo

# after
export LTX2_TWO_STAGE_DEVICE_MODE=original

Defensive patterns

Strategy: validation

Validate before calling

from sglang.multimodal_gen.runtime.pipelines.ltx_2_pipeline import LTX2_TWO_STAGE_DEVICE_MODE_CHOICES
mode = os.environ.get('LTX2_TWO_STAGE_DEVICE_MODE', 'original')
assert mode in LTX2_TWO_STAGE_DEVICE_MODE_CHOICES, f'bad mode {mode!r}'

Type guard

def is_valid_ltx2_mode(mode: str) -> bool:
    return mode in LTX2_TWO_STAGE_DEVICE_MODE_CHOICES

Prevention

Validate env-derived config values at process start
Re-check the CHOICES constant after sglang upgrades

When it happens

Trigger: Passing an invalid mode string (typo like 'orginal', unsupported value like 'cpu') to the two-stage device-mode resolver; exporting LTX2_TWO_STAGE_DEVICE_MODE with a misspelled value that gets picked up at startup.

Common situations: Typos in env vars or config files; modes renamed/removed across sglang versions so old configs now fail; copying a mode name from outdated docs.

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

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