{"record":{"id":"1a38a91561f8a15c","repo":"sgl-project/sglang","slug":"load-diffusion-decoder-was-requested-but-this-c","errorCode":null,"errorMessage":"--load-diffusion-decoder was requested, but this checkpoint does not declare a diffusion_decoder component.","messagePattern":"--load-diffusion-decoder was requested, but this checkpoint does not declare a diffusion_decoder component\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py","lineNumber":356,"sourceCode":"    ]\n\n    # `model_index.json` points at the distilled DiT; the full / SFT weights in\n    # `transformer_full/` are deliberately omitted from it.\n    _DEV_VARIANTS = frozenset({\"dev\", \"full\", \"sft\"})\n    _DEV_TRANSFORMER_SUBFOLDER = \"transformer_full\"\n\n    def __init__(self, model_path, server_args, required_config_modules=None, **kwargs):\n        self._maybe_route_dev_transformer(model_path, server_args)\n        # LTX-2 / 2.3 ship neither. The small duration head is always available\n        # when declared; the much larger decoder is loaded only on request.\n        modules = list(required_config_modules or self._required_config_modules)\n        if \"duration_head\" not in modules and self._declares_component(\n            model_path, \"duration_head\"\n        ):\n            modules.append(\"duration_head\")\n        if server_args.load_diffusion_decoder:\n            if not self._declares_component(model_path, \"diffusion_decoder\"):\n                raise ValueError(\n                    \"--load-diffusion-decoder was requested, but this checkpoint \"\n                    \"does not declare a diffusion_decoder component.\"\n                )\n            if \"diffusion_decoder\" not in modules:\n                modules.append(\"diffusion_decoder\")\n        super().__init__(\n            model_path, server_args, required_config_modules=modules, **kwargs\n        )\n\n    @classmethod\n    def _is_dev_variant(cls, server_args: ServerArgs) -> bool:\n        return str(server_args.model_variant or \"\").lower() in cls._DEV_VARIANTS\n\n    @classmethod\n    def _maybe_route_dev_transformer(cls, model_path: str, server_args: ServerArgs):\n        \"\"\"Point the transformer at `transformer_full/` for the dev variant.\"\"\"\n        if not cls._is_dev_variant(server_args):\n            return","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py#L338-L374","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove --load-diffusion-decoder for this checkpoint","Or switch to a checkpoint that actually includes the diffusion_decoder component (check its manifest/model_index.json first)","Re-download the snapshot completely (huggingface-cli download <repo>) if the component should exist but was skipped"],"exampleFix":"# before\npython -m sglang.launch_server --model-path ltx2-base --load-diffusion-decoder\n\n# after\npython -m sglang.launch_server --model-path ltx2-base\n# or use a checkpoint that declares diffusion_decoder","handlingStrategy":"validation","validationCode":"import json, pathlib\nmi = json.loads(pathlib.Path(model_path, 'model_index.json').read_text()) if pathlib.Path(model_path, 'model_index.json').exists() else {}\nif server_args.load_diffusion_decoder and 'diffusion_decoder' not in mi:\n    server_args.load_diffusion_decoder = False  # or abort with a clear message","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Inspect the checkpoint manifest before enabling component-load flags","Keep flag sets per checkpoint in versioned launch configs"],"tags":["ltx2","diffusion-decoder","checkpoint-manifest","sglang"],"backgroundTag":"checkpoint-component-missing","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}