sgl-project/sglang · error · ValueError

--load-diffusion-decoder was requested, but this checkpoint

Error message

--load-diffusion-decoder was requested, but this checkpoint does not declare a diffusion_decoder component.

What it means

Raised by the LTX-2 pipeline constructor when --load-diffusion-decoder is set but the checkpoint's metadata does not declare a diffusion_decoder component. The pipeline refuses to load a component the checkpoint does not ship, rather than failing later with missing weights.

Source

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

    ]

    # `model_index.json` points at the distilled DiT; the full / SFT weights in
    # `transformer_full/` are deliberately omitted from it.
    _DEV_VARIANTS = frozenset({"dev", "full", "sft"})
    _DEV_TRANSFORMER_SUBFOLDER = "transformer_full"

    def __init__(self, model_path, server_args, required_config_modules=None, **kwargs):
        self._maybe_route_dev_transformer(model_path, server_args)
        # LTX-2 / 2.3 ship neither. The small duration head is always available
        # when declared; the much larger decoder is loaded only on request.
        modules = list(required_config_modules or self._required_config_modules)
        if "duration_head" not in modules and self._declares_component(
            model_path, "duration_head"
        ):
            modules.append("duration_head")
        if server_args.load_diffusion_decoder:
            if not self._declares_component(model_path, "diffusion_decoder"):
                raise ValueError(
                    "--load-diffusion-decoder was requested, but this checkpoint "
                    "does not declare a diffusion_decoder component."
                )
            if "diffusion_decoder" not in modules:
                modules.append("diffusion_decoder")
        super().__init__(
            model_path, server_args, required_config_modules=modules, **kwargs
        )

    @classmethod
    def _is_dev_variant(cls, server_args: ServerArgs) -> bool:
        return str(server_args.model_variant or "").lower() in cls._DEV_VARIANTS

    @classmethod
    def _maybe_route_dev_transformer(cls, model_path: str, server_args: ServerArgs):
        """Point the transformer at `transformer_full/` for the dev variant."""
        if not cls._is_dev_variant(server_args):
            return

View on GitHub (pinned to 0132848349)

Solutions

  1. Remove --load-diffusion-decoder for this checkpoint
  2. Or switch to a checkpoint that actually includes the diffusion_decoder component (check its manifest/model_index.json first)
  3. Re-download the snapshot completely (huggingface-cli download <repo>) if the component should exist but was skipped

Example fix

# before
python -m sglang.launch_server --model-path ltx2-base --load-diffusion-decoder

# after
python -m sglang.launch_server --model-path ltx2-base
# or use a checkpoint that declares diffusion_decoder
Defensive patterns

Strategy: validation

Validate before calling

import json, pathlib
mi = json.loads(pathlib.Path(model_path, 'model_index.json').read_text()) if pathlib.Path(model_path, 'model_index.json').exists() else {}
if server_args.load_diffusion_decoder and 'diffusion_decoder' not in mi:
    server_args.load_diffusion_decoder = False  # or abort with a clear message

Prevention

When it happens

Trigger: Launching with server_args.load_diffusion_decoder=True against an LTX-2 checkpoint whose model_index.json / component manifest lacks a diffusion_decoder entry; using a base-only or partially downloaded snapshot with the decoder flag on.

Common situations: Confusing checkpoints: some LTX-2 releases ship the diffusion decoder, others (or stripped re-uploads) do not; enabling the flag by copy-paste from docs for a different checkpoint; interrupted HF snapshot downloads that dropped component dirs.

Related errors

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