sgl-project/sglang · error · ValueError

--model-variant {server_args.model_variant} requires '{cls._

Error message

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

What it means

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.

Source

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

                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
        if server_args.component_paths.get("transformer"):
            return
        full_path = os.path.join(str(model_path), cls._DEV_TRANSFORMER_SUBFOLDER)
        if not os.path.isdir(full_path):
            raise ValueError(
                f"--model-variant {server_args.model_variant} requires "
                f"'{cls._DEV_TRANSFORMER_SUBFOLDER}' in the checkpoint, but "
                f"{full_path} does not exist. It is excluded from "
                "`model_index.json`, so a partial snapshot download may have "
                "skipped it."
            )
        server_args.component_paths["transformer"] = full_path
        logger.info("Serving the LTX-2.5 dev transformer from %s", full_path)

    @staticmethod
    def _declares_component(model_path: str, component_name: str) -> bool:
        index_path = os.path.join(str(model_path), "model_index.json")
        if not os.path.exists(index_path):
            return False
        try:
            with open(index_path) as f:
                model_index = json.load(f)
        except (OSError, ValueError):

View on GitHub (pinned to 0132848349)

Solutions

1. Download the full snapshot (e.g. huggingface-cli download <repo> --local-dir ...) so the excluded subfolder is fetched
2. Verify os.path.isdir(<model_path>/<dev-transformer-subfolder>) before launch and re-fetch if missing
3. Or pass --component-paths transformer=<path> (component_paths['transformer']) pointing at an existing dev transformer, which bypasses the check
4. Or drop the dev --model-variant if you intended the standard transformer

Example fix

# before
huggingface-cli download ltx2-repo --include="*.json" --local-dir m  # skips dev folder
python -m sglang.launch_server --model-path m --model-variant dev

# after
huggingface-cli download ltx2-repo --local-dir m
python -m sglang.launch_server --model-path m --model-variant dev

from sglang.multimodal_gen.runtime.pipelines.ltx_2_pipeline import LTX2Pipeline
sub = LTX2Pipeline._DEV_TRANSFORMER_SUBFOLDER
if server_args.component_paths.get('transformer') is None and not os.path.isdir(os.path.join(model_path, sub)):
    raise SystemExit(f'missing {sub}; download the full snapshot or set component_paths["transformer"]')

When it happens

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

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

Related errors

• scale_shift_table must have shape [9, D]
• --load-diffusion-decoder was requested, but this checkpoint
• Invalid ltx2_two_stage_device_mode={mode!r}. Expected one of
• {self.pipeline_name} requires --spatial-upsampler-path (comp
• {self.pipeline_name} requires --distilled-lora-path (compone

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