sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache has invalid timestep plans

Error message

MiniMax H3 AdaLN cache has invalid timestep plans

What it means

The plan_timesteps/plan_lengths tensors inside the sidecar fail structural validation: wrong dtype (plan_lengths must be int64), wrong rank (plan_timesteps must be 2-D), plan_lengths shape not (num_plans,), or length values outside [1, max_timesteps]. The cache is corrupt or from an incompatible layout.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py:1204

                    "MiniMax H3 AdaLN cache model_variant does not match the loaded "
                    f"variant ({cache_variant!r} != {self.model_variant!r})"
                )
            plan_timesteps = cache_file.get_tensor("plan_timesteps")
            plan_lengths = cache_file.get_tensor("plan_lengths")
            block_params = cache_file.get_tensor("block_params")
            final_params = cache_file.get_tensor("final_params")

        expected_block_width = 6 * MINIMAX_H3_ADALN_MODALITY_NUM * self.hidden_size
        expected_final_width = 2 * self.hidden_size
        if (
            plan_timesteps.dtype != _FP32_DTYPE
            or plan_timesteps.ndim != 2
            or plan_lengths.dtype != torch.int64
            or plan_lengths.shape != (plan_timesteps.shape[0],)
            or (plan_lengths < 1).any()
            or (plan_lengths > plan_timesteps.shape[1]).any()
        ):
            raise ValueError("MiniMax H3 AdaLN cache has invalid timestep plans")
        if block_params.dtype != _BF16_DTYPE or block_params.shape != (
            plan_timesteps.shape[0],
            plan_timesteps.shape[1],
            self.num_layers,
            expected_block_width,
        ):
            raise ValueError("MiniMax H3 AdaLN cache has invalid block_params")
        if final_params.dtype != _BF16_DTYPE or final_params.shape != (
            plan_timesteps.shape[0],
            plan_timesteps.shape[1],
            expected_final_width,
        ):
            raise ValueError("MiniMax H3 AdaLN cache has invalid final_params")

        self.register_buffer("plan_timesteps", plan_timesteps.to(device))
        self.register_buffer("plan_lengths", plan_lengths.to(device))
        self.register_buffer("block_params", block_params.to(device))
        self.register_buffer("final_params", final_params.to(device))

View on GitHub (pinned to 0132848349)

Solutions

1. Regenerate the sidecar from the checkpoint (weight_files mode)
2. If it persists after regeneration, inspect the tensors with safetensors.safe_open to see which invariant breaks and report a bug
3. Validate sidecars with a checksum after generation to catch truncation

Example fix

# before
cache = MinimaxH3AdaLNCache(path="possibly_corrupt/adaln_cache.safetensors")
# after
from safetensors import safe_open
with safe_open(path, framework="pt") as f:  # sanity-check tensors
    assert f.get_tensor("plan_lengths").dtype == torch.int64
cache = MinimaxH3AdaLNCache(path=path)

with safe_open(path, framework="pt") as f:
    t, l = f.get_tensor("plan_timesteps"), f.get_tensor("plan_lengths")
    ok = (t.ndim == 2 and l.dtype == torch.int64
          and l.shape == (t.shape[0],)
          and (l >= 1).all() and (l <= t.shape[1]).all())

def plans_valid(t: "torch.Tensor", l: "torch.Tensor") -> bool:
    return (t.ndim == 2 and l.dtype == torch.int64
            and l.shape == (t.shape[0],)
            and bool((l >= 1).all()) and bool((l <= t.shape[1]).all()))

try:
    cache.load(device)
except ValueError as e:
    if "invalid timestep plans" in str(e):
        cache = MinimaxH3AdaLNCache(weight_files=shards)  # rebuild corrupt cache
    else:
        raise

When it happens

Trigger: load() reads plan_timesteps and plan_lengths and any of: dtype mismatch, ndim != 2, per-plan lengths < 1 or > plan_timesteps.shape[1], or plan_lengths.shape[0] != plan_timesteps.shape[0].

Common situations: Corrupted or truncated sidecar from an interrupted write, a file written by different builder logic, or manual editing of the safetensors cache.

Related errors

• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• --minimax-h3-adaln-cache-path requires the unquantized trans
• MiniMax H3 AdaLN cache takes exactly one of path (prebuilt s
• MiniMax H3 AdaLN cache max_plans must be positive
• MiniMax H3 AdaLN cache max_plan_width must be positive; set

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