sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache max_plans must be positive

Error message

MiniMax H3 AdaLN cache max_plans must be positive

What it means

The AdaLN plan cache is sized by max_plans (how many distinct timestep plans it can hold); a value below 1 makes the cache useless, so it is rejected at construction. The default is 64.

Source

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

    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
        self.final_width = 2 * arch.hidden_size
        # Rebuild path only: plan bit pattern -> slot, tracked on the host.
        self._slots: dict[tuple[int, ...], int] = {}
        self.rebuilds = 0

View on GitHub (pinned to 0132848349)

Solutions

1. Pass max_plans >= 1 (keep default 64 unless tuning)
2. If 0 should mean unlimited in your tooling, translate it to a large positive value before construction

Example fix

# before
cache = MinimaxH3AdaLNCache(weight_files=fs, max_plans=0)
# after
cache = MinimaxH3AdaLNCache(weight_files=fs, max_plans=64)

max_plans = max(1, int(max_plans))
# or reject explicitly:
if max_plans < 1: raise ValueError("max_plans must be >= 1")

def valid_max_plans(v: int) -> bool:
    return isinstance(v, int) and v >= 1

When it happens

Trigger: Constructing the cache with max_plans=0 or a negative value, usually from an explicit argument or a miscomputed config value.

Common situations: A CLI/config knob wired straight into max_plans with 0 meaning 'unlimited' in the user's mind, or an arithmetic expression that can underflow to 0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• MiniMax H3 AdaLN cache takes exactly one of path (prebuilt s
• MiniMax H3 AdaLN cache max_plan_width must be positive; set
• --minimax-h3-adaln-cache-path requires the unquantized trans
• MiniMax H3 AdaLN cache does not exist: {self.path}
• MiniMax H3 AdaLN cache has an unsupported or missing format_

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