sgl-project/sglang · error · ValueError

MiniMax-H3 checkpoint shards disagree on adaln_t_table shape

Error message

MiniMax-H3 checkpoint shards disagree on adaln_t_table shape: {adaln_curve_shape} vs {shape}

What it means

All shards of a MiniMax-H3 checkpoint must agree on the shape of adaln_t_table, since the curve table is a single model-level asset. The inspector records the first shape it sees and raises if a later shard reports a different one.

Source

Thrown at python/sglang/multimodal_gen/runtime/loader/minimax_h3_weights.py:43

def inspect_minimax_h3_safetensors(
    safetensors_list: list[str],
) -> tuple[tuple[int, int] | None, dict[str, dict[str, Any]]]:
    """Read H3 architecture metadata and Comfy per-layer format markers."""
    adaln_curve_shape = None
    layer_markers = inspect_comfy_quant_markers(safetensors_list)

    for path in safetensors_list:
        with safe_open(path, framework="pt", device="cpu") as checkpoint:
            keys = checkpoint.keys()
            if "adaln_t_table" in keys:
                shape = tuple(checkpoint.get_slice("adaln_t_table").get_shape())
                if len(shape) != 2 or shape[0] < 2:
                    raise ValueError(
                        "MiniMax-H3 adaln_t_table must have shape [N, D] with "
                        f"N >= 2, got {shape} in {path}"
                    )
                if adaln_curve_shape is not None and adaln_curve_shape != shape:
                    raise ValueError(
                        "MiniMax-H3 checkpoint shards disagree on adaln_t_table "
                        f"shape: {adaln_curve_shape} vs {shape}"
                    )
                adaln_curve_shape = shape

    return adaln_curve_shape, layer_markers


def resolve_minimax_h3_checkpoint_quantization(
    layer_markers: dict[str, dict[str, Any]],
    safetensors_list: list[str] | None = None,
    param_names_mapping: dict | None = None,
    reverse_param_names_mapping: dict | None = None,
) -> QuantizationConfig | None:
    formats = {str(marker.get("format")) for marker in layer_markers.values()}
    if "nvfp4" in formats:
        unsupported = formats - {"nvfp4", "int8_tensorwise", "float8_e4m3fn"}
        if unsupported:

View on GitHub (pinned to 0132848349)

Solutions

  1. Ensure only one shard carries adaln_t_table, or that all copies are byte-identical in shape
  2. Re-export the whole checkpoint in one consistent run
  3. If merging shards manually, delete duplicate adaln_t_table entries from all but one shard

Example fix

# before: shard A has adaln_t_table (64, 1152), shard B has (256, 1152) -> raise
# after: keep a single consistent copy across all shards
Defensive patterns

Strategy: validation

Validate before calling

shapes = set()
for path in safetensors_list:
    with safe_open(path, framework='pt') as f:
        if 'adaln_t_table' in f.keys():
            shapes.add(tuple(f.get_slice('adaln_t_table').get_shape()))
assert len(shapes) <= 1, f'shards disagree: {shapes}'

Type guard

def shards_agree(safetensors_list) -> bool:
    shapes = set()
    for path in safetensors_list:
        with safe_open(path, framework='pt') as f:
            if 'adaln_t_table' in f.keys():
                shapes.add(tuple(f.get_slice('adaln_t_table').get_shape()))
    return len(shapes) <= 1

Prevention

When it happens

Trigger: Loading multi-shard MiniMax-H3 safetensors where two shards contain adaln_t_table tensors with different shapes, e.g. (64, 1152) in one shard and (256, 1152) in another.

Common situations: Concatenating checkpoints from different MiniMax-H3 versions or resolutions; a duplicated table saved into every shard during a buggy export where some shards carry a stale copy; mixing base and fine-tuned shards.

Related errors

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