sgl-project/sglang · error · ValueError

{self.pipeline_name} requires --spatial-upsampler-path (comp

Error message

{self.pipeline_name} requires --spatial-upsampler-path (component_paths['spatial_upsampler']).

What it means

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.

Source

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

            server_args.pipeline_config.vae_config.arch_config
        )

    def _should_merge_lora_for_phase(self, phase: str) -> bool:
        if phase == "stage2" and self._ltx2_residency.mode == "original":
            # original mode reuses one DiT for both phases; dynamic LoRA avoids
            # request-time merge/unmerge without keeping another DiT resident
            return False
        return self._should_merge_stage2_distilled_lora(self.server_args)

    def initialize_pipeline(self, server_args: ServerArgs):
        super().initialize_pipeline(server_args)
        server_args.component_paths = _resolve_ltx2_two_stage_component_paths(
            self.model_path, server_args.component_paths
        )

        upsampler_path = server_args.component_paths.get("spatial_upsampler")
        if not upsampler_path:
            raise ValueError(
                f"{self.pipeline_name} requires --spatial-upsampler-path "
                "(component_paths['spatial_upsampler'])."
            )
        module, memory_usage = PipelineComponentLoader.load_component(
            component_name="spatial_upsampler",
            component_model_path=upsampler_path,
            transformers_or_diffusers="diffusers",
            server_args=server_args,
        )
        self.modules["spatial_upsampler"] = module
        self.memory_usages["spatial_upsampler"] = memory_usage

        # LTX-2 / 2.3 merge a distilled LoRA per stage; LTX-2.5's transformer
        # is already distilled, so the LoRA is optional there.
        distilled_lora_path = server_args.component_paths.get("distilled_lora")
        if not distilled_lora_path and not self._transformer_is_predistilled(
            server_args
        ):

View on GitHub (pinned to 0132848349)

Solutions

1. Pass --spatial-upsampler-path <dir> pointing at the spatial upsampler checkpoint
2. If the upsampler lives inside the model repo, point the flag at that subdirectory
3. Verify the path exists on the node actually loading the model (not just the launcher)

Example fix

# before
python -m sglang.launch_server --model-path ltx2 ...

# after
python -m sglang.launch_server --model-path ltx2 --spatial-upsampler-path /models/ltx2-spatial-upsampler

if not server_args.component_paths.get('spatial_upsampler'):
    raise SystemExit('LTX-2 two-stage requires --spatial-upsampler-path')
assert os.path.isdir(server_args.component_paths['spatial_upsampler'])

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• {self.pipeline_name} requires --distilled-lora-path (compone
• --load-diffusion-decoder was requested, but this checkpoint
• --model-variant {server_args.model_variant} requires '{cls._
• Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of
• Unknown serve backend {name!r}. Available values: {available

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