{"record":{"id":"352ff3b1f45b7807","repo":"sgl-project/sglang","slug":"model-variant-server-args-model-variant-requir","errorCode":null,"errorMessage":"--model-variant {server_args.model_variant} requires '{cls._DEV_TRANSFORMER_SUBFOLDER}' in the checkpoint, but {full_path} does not exist. It is excluded from `model_index.json`, so a partial snapshot download may have skipped it.","messagePattern":"--model-variant (.+?) requires '(.+?)' in the checkpoint, but (.+?) does not exist\\. It is excluded from `model_index\\.json`, so a partial snapshot download may have skipped it\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py","lineNumber":379,"sourceCode":"                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\n        if server_args.component_paths.get(\"transformer\"):\n            return\n        full_path = os.path.join(str(model_path), cls._DEV_TRANSFORMER_SUBFOLDER)\n        if not os.path.isdir(full_path):\n            raise ValueError(\n                f\"--model-variant {server_args.model_variant} requires \"\n                f\"'{cls._DEV_TRANSFORMER_SUBFOLDER}' in the checkpoint, but \"\n                f\"{full_path} does not exist. It is excluded from \"\n                \"`model_index.json`, so a partial snapshot download may have \"\n                \"skipped it.\"\n            )\n        server_args.component_paths[\"transformer\"] = full_path\n        logger.info(\"Serving the LTX-2.5 dev transformer from %s\", full_path)\n\n    @staticmethod\n    def _declares_component(model_path: str, component_name: str) -> bool:\n        index_path = os.path.join(str(model_path), \"model_index.json\")\n        if not os.path.exists(index_path):\n            return False\n        try:\n            with open(index_path) as f:\n                model_index = json.load(f)\n        except (OSError, ValueError):","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py#L361-L397","documentation":"Raised by LTX2Pipeline._maybe_route_dev_transformer when --model-variant selects a dev variant but the required transformer subfolder is absent from the checkpoint. That subfolder is deliberately excluded from model_index.json, so HF partial downloads driven by the manifest can skip it entirely.","triggerScenarios":"Launching with server_args.model_variant set to a dev variant while the checkpoint directory lacks the dev-transformer subfolder; snapshots downloaded via model_index.json-driven tooling that never fetched the excluded folder.","commonSituations":"Using huggingface-cli download with include patterns derived from model_index.json; resuming a partial download; cloning an LFS repo without pulling all folders; pointing --model-path at a local pruned copy.","solutions":["Download the full snapshot (e.g. huggingface-cli download <repo> --local-dir ...) so the excluded subfolder is fetched","Verify os.path.isdir(<model_path>/<dev-transformer-subfolder>) before launch and re-fetch if missing","Or pass --component-paths transformer=<path> (component_paths['transformer']) pointing at an existing dev transformer, which bypasses the check","Or drop the dev --model-variant if you intended the standard transformer"],"exampleFix":"# before\nhuggingface-cli download ltx2-repo --include=\"*.json\" --local-dir m  # skips dev folder\npython -m sglang.launch_server --model-path m --model-variant dev\n\n# after\nhuggingface-cli download ltx2-repo --local-dir m\npython -m sglang.launch_server --model-path m --model-variant dev","handlingStrategy":"validation","validationCode":"from sglang.multimodal_gen.runtime.pipelines.ltx_2_pipeline import LTX2Pipeline\nsub = LTX2Pipeline._DEV_TRANSFORMER_SUBFOLDER\nif server_args.component_paths.get('transformer') is None and not os.path.isdir(os.path.join(model_path, sub)):\n    raise SystemExit(f'missing {sub}; download the full snapshot or set component_paths[\"transformer\"]')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Download full snapshots rather than manifest-driven subsets for LTX checkpoints","Pre-flight check required subdirectories before launching dev variants"],"tags":["ltx2","model-variant","partial-download","checkpoint","sglang"],"backgroundTag":"partial-checkpoint-download","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}