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

After computing timestep plans from the args, either no plans were produced or some plan has zero timesteps, so there is nothing to cache and the output tensors would be empty/degenerate.

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)

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
• 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/3548b95038fb257d. Report an issue: GitHub.