sgl-project/sglang · error · ValueError

--mode {args.mode} requires {mode_variant}

Error message

--mode {args.mode} requires {mode_variant}

What it means

Each --mode of the cache builder is only valid for one specific --model-variant (looked up in _MODE_VARIANTS); passing a mismatched pair is rejected early before any heavy work.

Source

Thrown at python/sglang/multimodal_gen/tools/build_minimax_h3_adaln_cache.py:156

def _load_tensor(
    name: str,
    *,
    weight_map: dict[str, str],
    files: dict[str, Any],
    device: torch.device,
) -> torch.Tensor:
    tensor_file = files[weight_map[name]]
    return tensor_file.get_tensor(name).to(device)


def main() -> None:
    args = _parse_args()
    if args.num_inference_steps < 2 and args.timesteps is None:
        raise ValueError("--num-inference-steps must be at least 2")
    mode_variant = _MODE_VARIANTS[args.mode]
    if args.model_variant != mode_variant:
        raise ValueError(f"--mode {args.mode} requires {mode_variant}")
    device = torch.device(args.device)
    if device.type != "cuda" or not torch.cuda.is_available():
        raise ValueError("MiniMax H3 AdaLN cache must be built on CUDA")

    index_path = args.transformer_path / "model.safetensors.index.json"
    with index_path.open() as f:
        weight_map = json.load(f)["weight_map"]

    plans = _cache_timestep_plans(args)
    if not plans or any(plan.numel() == 0 for plan in plans):
        raise ValueError("AdaLN cache must cover at least one timestep plan")
    max_plan_length = max(plan.numel() for plan in plans)
    plan_timesteps = torch.zeros((len(plans), max_plan_length), dtype=torch.float32)
    plan_lengths = torch.tensor([plan.numel() for plan in plans], dtype=torch.int64)
    block_params = torch.empty(
        (len(plans), max_plan_length, _NUM_BLOCKS, _BLOCK_PARAM_WIDTH),
        dtype=torch.bfloat16,
    )

View on GitHub (pinned to 0132848349)

Solutions

1. Check _MODE_VARIANTS in the tool to see which variant the mode requires
2. Set --model-variant to the value named in the error message
3. Or switch --mode to one compatible with your variant

Example fix

# before
--mode video --model-variant minimax-h3-base
# after
--mode video --model-variant minimax-h3-video

if _MODE_VARIANTS[args.mode] != args.model_variant:
    raise SystemExit(f"{args.mode} requires {_MODE_VARIANTS[args.mode]}")

When it happens

Trigger: E.g. selecting --mode for the text-only variant while --model-variant points at the multimodal checkpoint, or vice versa.

Common situations: Reusing a command line from a sibling model; mode/variant names drifting between versions of the tool.

Related errors

• {option} must use component=value entries
• component_attention_backends must use component=backend entr
• Invalid --warmup-mode {self.warmup_mode!r}; expected one of
• --warmup-num-frames must be a positive integer.
• --num-inference-steps must be at least 2

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