sgl-project/sglang · error · ValueError

ltx2_two_stage_device_mode=resident conflicts with explicit

Error message

ltx2_two_stage_device_mode=resident conflicts with explicit component residency: {configured}

What it means

When ltx2_two_stage_device_mode resolves to 'resident' but some DiT components have explicit non-resident residency modes configured, the explicit mode wins and the conflict is an error if 'resident' was explicitly requested (via flag or env); otherwise it silently downgrades to 'original' with a log line.

Source

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

        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 "
                    f"component residency: {configured}"
                )
            mode = "original"
            logger.info(
                "Using ltx2_two_stage_device_mode=original because DiT offload "
                "was explicitly configured: %s",
                configured,
            )

        self.ltx2_two_stage_device_mode = mode

    def _resolve_default_ltx2_two_stage_device_mode(self) -> str:
        if not current_platform.is_cuda():
            logger.info(
                "Automatically set ltx2_two_stage_device_mode=original on non-CUDA platform"
            )
            return "original"

View on GitHub (pinned to 0132848349)

Solutions

1. Remove or align the per-component residency settings so all components are resident, or
2. Change ltx2_two_stage_device_mode to a compatible value such as 'original'
3. Unset the env var if the 'resident' mode was unintentionally inherited

Example fix

# before
ServerArgs(ltx2_two_stage_device_mode="resident", ltx2_dit_residency="offloaded")
# after
ServerArgs(ltx2_two_stage_device_mode="resident")

explicit_nonresident = [k for k, v in component_residency.items() if v != 'resident']
if cfg.get('ltx2_two_stage_device_mode') == 'resident' and explicit_nonresident:
    cfg['ltx2_two_stage_device_mode'] = 'original'  # or drop the per-component settings

When it happens

Trigger: Setting ltx2_two_stage_device_mode='resident' (or its env var) while also configuring component residency (e.g. ltx2_*_residency='offloaded') for any DiT component; the code builds explicit_nonresident_dits and detects the clash.

Common situations: Migrating a per-component offload config to the umbrella mode flag and forgetting to remove the old per-component settings; env var leaking an explicit mode into a config that also sets per-component residency.

Related errors

• Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of
• ReplaySSM inputs must be on the same device.
• `force_flush` must be on the same device as the inputs.
• timestep must have shape [B, S, 9 * D]
• timestep must be a CUDA bfloat16 tensor

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