{"record":{"id":"4218bca743023477","repo":"sgl-project/sglang","slug":"self-pipeline-name-requires-spatial-upsampler","errorCode":null,"errorMessage":"{self.pipeline_name} requires --spatial-upsampler-path (component_paths['spatial_upsampler']).","messagePattern":"(.+?) requires --spatial-upsampler-path \\(component_paths\\['spatial_upsampler'\\]\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py","lineNumber":679,"sourceCode":"            server_args.pipeline_config.vae_config.arch_config\n        )\n\n    def _should_merge_lora_for_phase(self, phase: str) -> bool:\n        if phase == \"stage2\" and self._ltx2_residency.mode == \"original\":\n            # original mode reuses one DiT for both phases; dynamic LoRA avoids\n            # request-time merge/unmerge without keeping another DiT resident\n            return False\n        return self._should_merge_stage2_distilled_lora(self.server_args)\n\n    def initialize_pipeline(self, server_args: ServerArgs):\n        super().initialize_pipeline(server_args)\n        server_args.component_paths = _resolve_ltx2_two_stage_component_paths(\n            self.model_path, server_args.component_paths\n        )\n\n        upsampler_path = server_args.component_paths.get(\"spatial_upsampler\")\n        if not upsampler_path:\n            raise ValueError(\n                f\"{self.pipeline_name} requires --spatial-upsampler-path \"\n                \"(component_paths['spatial_upsampler']).\"\n            )\n        module, memory_usage = PipelineComponentLoader.load_component(\n            component_name=\"spatial_upsampler\",\n            component_model_path=upsampler_path,\n            transformers_or_diffusers=\"diffusers\",\n            server_args=server_args,\n        )\n        self.modules[\"spatial_upsampler\"] = module\n        self.memory_usages[\"spatial_upsampler\"] = memory_usage\n\n        # LTX-2 / 2.3 merge a distilled LoRA per stage; LTX-2.5's transformer\n        # is already distilled, so the LoRA is optional there.\n        distilled_lora_path = server_args.component_paths.get(\"distilled_lora\")\n        if not distilled_lora_path and not self._transformer_is_predistilled(\n            server_args\n        ):","sourceCodeStart":661,"sourceCodeEnd":697,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py#L661-L697","documentation":"Raised by LTX2Pipeline.initialize_pipeline when component_paths['spatial_upsampler'] is empty. The two-stage LTX-2 pipeline requires the spatial upsampler weights at stage 2, and no default location exists, so startup aborts with an explicit pointer to the --spatial-upsampler-path flag.","triggerScenarios":"Launching an LTX-2 two-stage pipeline without --spatial-upsampler-path (or component_paths['spatial_upsampler']); path resolution helpers returned nothing because the upsampler is not co-located with the main model.","commonSituations":"New LTX-2 deployments where the upsampler ships as a separate repo/directory; configs migrated from single-stage setups that never needed the flag; empty-string component paths from templated launch scripts.","solutions":["Pass --spatial-upsampler-path <dir> pointing at the spatial upsampler checkpoint","If the upsampler lives inside the model repo, point the flag at that subdirectory","Verify the path exists on the node actually loading the model (not just the launcher)"],"exampleFix":"# before\npython -m sglang.launch_server --model-path ltx2 ...\n\n# after\npython -m sglang.launch_server --model-path ltx2 --spatial-upsampler-path /models/ltx2-spatial-upsampler","handlingStrategy":"validation","validationCode":"if not server_args.component_paths.get('spatial_upsampler'):\n    raise SystemExit('LTX-2 two-stage requires --spatial-upsampler-path')\nassert os.path.isdir(server_args.component_paths['spatial_upsampler'])","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add launch-time assertions for required component paths","Store per-model component path maps in one config source"],"tags":["ltx2","spatial-upsampler","missing-path","component","sglang"],"backgroundTag":"missing-component-path","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}