sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache takes exactly one of path (prebuilt s

Error message

MiniMax H3 AdaLN cache takes exactly one of path (prebuilt sidecar) or weight_files (rebuild from the checkpoint)

What it means

The MiniMax H3 AdaLN cache must be initialized in exactly one mode: either load a prebuilt sidecar file (path) or rebuild plans from checkpoint weight files (weight_files). Supplying both or neither is ambiguous, so the constructor rejects it.

Source

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

    _FORMAT_VERSION = "2"
    plan_timesteps: torch.Tensor
    plan_lengths: torch.Tensor
    block_params: torch.Tensor
    final_params: torch.Tensor

    def __init__(
        self,
        arch: MiniMaxH3DiTArchConfig,
        *,
        path: str | None = None,
        model_variant: str | None = None,
        weight_files: list[str] | None = None,
        max_plans: int = 64,
        max_plan_width: int = MINIMAX_H3_ADALN_MAX_PLAN_WIDTH,
    ) -> None:
        super().__init__()
        if (path is None) == (weight_files is None):
            raise ValueError(
                "MiniMax H3 AdaLN cache takes exactly one of path (prebuilt "
                "sidecar) or weight_files (rebuild from the checkpoint)"
            )
        if max_plans < 1:
            raise ValueError("MiniMax H3 AdaLN cache max_plans must be positive")
        if max_plan_width < 1:
            raise ValueError(
                "MiniMax H3 AdaLN cache max_plan_width must be positive; "
                "set --minimax-h3-adaln-plan-width to at least 1"
            )
        self.path = path
        self.model_variant = model_variant
        self.weight_files = weight_files
        self.max_plans = max_plans
        self.max_plan_width = max_plan_width
        self.num_layers = arch.num_layers
        self.hidden_size = arch.hidden_size
        self.block_width = 6 * MINIMAX_H3_ADALN_MODALITY_NUM * arch.hidden_size

View on GitHub (pinned to 0132848349)

Solutions

Pick one mode: pass path to an existing prebuilt sidecar, or pass weight_files to rebuild
If rebuilding, gather the checkpoint shard files and pass them as weight_files
If loading, ensure the sidecar path is a real file produced by a prior build

Example fix

# before
cache = MinimaxH3AdaLNCache(path=None, weight_files=None)
# after
cache = MinimaxH3AdaLNCache(path="ckpt/adaln_cache.safetensors")
# or
cache = MinimaxH3AdaLNCache(weight_files=["ckpt/shard0.safetensors", ...])

Defensive patterns

Strategy: validation

Validate before calling

assert (path is None) != (weight_files is None), "pass exactly one of path or weight_files"

Type guard

def exactly_one_mode(path: str | None, weight_files: list[str] | None) -> bool:
    return (path is None) != (weight_files is None)

Prevention

Use an Options/dataclass so only one mode field can be set
Document the two modes at the config layer

When it happens

Trigger: Constructing the cache with both path and weight_files set, or both None — the XOR check (path is None) == (weight_files is None) fires either way.

Common situations: Config plumbing that passes through both options, defaults that leave both unset when a sidecar path was expected, or a refactor that renamed one parameter leaving callers passing neither.

Related errors

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