sgl-project/sglang · error · ValueError

AdaLN cache must cover at least one timestep plan

Error message

AdaLN cache must cover at least one timestep plan

What it means

Validation error: the AdaLN cache configuration covers zero timestep plans; at least one timestep plan must be covered by the cache.

Solutions

1. Inspect _cache_timestep_plans to see how plans derive from your args
2. Use the default --num-inference-steps instead of a custom --timesteps
3. Ensure the timestep list is non-empty and within valid range

plans = _cache_timestep_plans(args)
if not plans or any(p.numel() == 0 for p in plans):
    raise SystemExit("empty timestep plan; check --timesteps/--num-inference-steps")

When it happens

Trigger: A --timesteps schedule that filters down to an empty set, or argument combinations (steps/shift/schedule) yielding zero effective timesteps for every plan.

Common situations: Custom timestep strings with only invalid/filtered entries; edge-valued scheduler parameters.

Related errors

• --num-inference-steps must be at least 2
• component_attention_backends must use component=backend…
• denoising_strength must be positive
• GGUF tensor declares original shape , which contains…
• Got but expected positional dim

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

Appendix: source

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

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,
    )
    final_params = torch.empty(
        (len(plans), max_plan_length, _FINAL_PARAM_WIDTH), dtype=torch.bfloat16
    )

    with ExitStack() as stack:
        files = {
            filename: stack.enter_context(
                safe_open(
                    str(args.transformer_path / filename),
                    framework="pt",
                    device="cpu",

View on GitHub (pinned to 0132848349)