sgl-project/sglang · error · ValueError

--num-inference-steps must be at least 2

Error message

--num-inference-steps must be at least 2

What it means

The MiniMax H3 AdaLN cache builder validates that --num-inference-steps is at least 2 unless an explicit --timesteps schedule overrides it. Fewer steps make the cached timestep plan degenerate.

Source

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

        proj_out_bias,
    )


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(

View on GitHub (pinned to 0132848349)

Solutions

1. Pass --num-inference-steps >= 2
2. Or supply an explicit --timesteps schedule if you truly need a custom plan

Example fix

# before
--num-inference-steps 1
# after
--num-inference-steps 2

if args.num_inference_steps is not None and args.num_inference_steps < 2 and args.timesteps is None:
    raise SystemExit("num-inference-steps must be >= 2 (or pass --timesteps)")

When it happens

Trigger: Running build_minimax_h3_adaln_cache.py with --num-inference-steps 0 or 1 and no --timesteps argument.

Common situations: Attempting to precompute a single-step cache by passing 1; copy-pasting a config tuned for a different scheduler.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• AdaLN cache must cover at least one timestep plan
• Validate failed: unsupported dtype: {t.dtype}
• Validate failed: unsupported tensor shape: {t.shape}.
• GGUF tensor {tensor.name} declares original shape {logical_s
• unknown qk_norm: {qk_norm}. Should be one of None, 'layer_no

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