sgl-project/sglang · error · ValueError

{self.pipeline_name} requires --distilled-lora-path (compone

Error message

{self.pipeline_name} requires --distilled-lora-path (component_paths['distilled_lora']).

What it means

Raised by LTX2Pipeline.initialize_pipeline when no distilled_lora component path is provided and the transformer is not pre-distilled. LTX-2 / 2.3 merge a distilled LoRA per stage for fast few-step sampling; only LTX-2.5's transformer (already distilled at train time) is exempt via _transformer_is_predistilled.

Source

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

                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
        ):
            raise ValueError(
                f"{self.pipeline_name} requires --distilled-lora-path "
                "(component_paths['distilled_lora'])."
            )
        self._distilled_lora_path = distilled_lora_path
        self._stage1_lora_path = server_args.lora_path
        self._stage1_lora_scale = float(server_args.lora_scale)
        self._active_lora_phase = None
        self._active_lora_signature = None
        self._use_premerged_stage2_transformer = False
        # set when original mode merges stage-1 distilled LoRA into the DiT base
        # once at init (see _merge_stage1_distilled_into_base).
        self._stage1_distilled_in_base = False
        self._stage1_distilled_base_strength: float | None = None

    @staticmethod
    def _transformer_is_predistilled(server_args: ServerArgs) -> bool:
        """Whether the checkpoint's own transformer is already distilled.

View on GitHub (pinned to 0132848349)

Solutions

Pass --distilled-lora-path <dir> for LTX-2 / 2.3 checkpoints
If you are actually running a pre-distilled (LTX-2.5-style) transformer, verify model_path points at the right checkpoint so _transformer_is_predistilled detects it and the flag becomes optional
Download the distilled LoRA artifact and confirm the directory exists before launch

Example fix

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

# after
python -m sglang.launch_server --model-path ltx2-2.3 --distilled-lora-path /models/ltx2-distilled-lora

Defensive patterns

Strategy: validation

Validate before calling

needs_lora = not pipeline._transformer_is_predistilled(server_args)
if needs_lora and not server_args.component_paths.get('distilled_lora'):
    raise SystemExit('this LTX-2 checkpoint requires --distilled-lora-path')

Prevention

Know your transformer generation: 2/2.3 need the distilled LoRA, 2.5 does not
Validate all component paths exist on the serving node before launch

When it happens

Trigger: Launching an LTX-2 or LTX-2.3 checkpoint without --distilled-lora-path; supplying the flag only via a config key the launcher ignores; running a 2.5-adjacent transformer whose checkpoint lacks the pre-distillation marker so the exemption check fails.

Common situations: Omitting the LoRA flag when copying a launch line from LTX-2.5 examples; separate-repo distilled LoRA artifacts not downloaded together with the base model; wrong model_path causing the predistilled probe to look at the wrong config.

Related errors

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