{"record":{"id":"830eee18438173aa","repo":"sgl-project/sglang","slug":"ltx2-two-stage-device-mode-resident-conflicts-with","errorCode":null,"errorMessage":"ltx2_two_stage_device_mode=resident conflicts with explicit component residency: {configured}","messagePattern":"ltx2_two_stage_device_mode=resident conflicts with explicit component residency: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/server_args/server_args.py","lineNumber":865,"sourceCode":"        if mode not in LTX2_TWO_STAGE_DEVICE_MODES:\n            raise ValueError(\n                f\"Invalid ltx2_two_stage_device_mode={mode!r}. \"\n                f\"Expected one of {LTX2_TWO_STAGE_DEVICE_MODE_CHOICES}.\"\n            )\n\n        explicit_nonresident_dits = {\n            component_name: residency_mode\n            for component_name in (\"transformer\", \"transformer_2\")\n            if (residency_mode := self.explicit_residency_mode(component_name))\n            in (COMPONENT_OFFLOAD, LAYERWISE_OFFLOAD)\n        }\n        if mode == \"resident\" and explicit_nonresident_dits:\n            configured = \", \".join(\n                f\"{name}={residency_mode}\"\n                for name, residency_mode in explicit_nonresident_dits.items()\n            )\n            if self.is_arg_explicitly_set(\"ltx2_two_stage_device_mode\") or env_mode:\n                raise ValueError(\n                    \"ltx2_two_stage_device_mode=resident conflicts with explicit \"\n                    f\"component residency: {configured}\"\n                )\n            mode = \"original\"\n            logger.info(\n                \"Using ltx2_two_stage_device_mode=original because DiT offload \"\n                \"was explicitly configured: %s\",\n                configured,\n            )\n\n        self.ltx2_two_stage_device_mode = mode\n\n    def _resolve_default_ltx2_two_stage_device_mode(self) -> str:\n        if not current_platform.is_cuda():\n            logger.info(\n                \"Automatically set ltx2_two_stage_device_mode=original on non-CUDA platform\"\n            )\n            return \"original\"","sourceCodeStart":847,"sourceCodeEnd":883,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/server_args/server_args.py#L847-L883","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove or align the per-component residency settings so all components are resident, or","Change ltx2_two_stage_device_mode to a compatible value such as 'original'","Unset the env var if the 'resident' mode was unintentionally inherited"],"exampleFix":"# before\nServerArgs(ltx2_two_stage_device_mode=\"resident\", ltx2_dit_residency=\"offloaded\")\n# after\nServerArgs(ltx2_two_stage_device_mode=\"resident\")","handlingStrategy":"validation","validationCode":"explicit_nonresident = [k for k, v in component_residency.items() if v != 'resident']\nif cfg.get('ltx2_two_stage_device_mode') == 'resident' and explicit_nonresident:\n    cfg['ltx2_two_stage_device_mode'] = 'original'  # or drop the per-component settings","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a single source of truth: either the umbrella mode or per-component residency, never both","Audit env vars (SGLANG_*) before launching so stale explicit modes don't leak in"],"tags":["ltx2","config-conflict","device-placement"],"backgroundTag":"conflicting-config-options","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}