sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache max_plan_width must be positive; set

Error message

MiniMax H3 AdaLN cache max_plan_width must be positive; set --minimax-h3-adaln-plan-width to at least 1

What it means

max_plan_width controls the widest timestep plan the AdaLN cache supports (bounded by MINIMAX_H3_ADALN_MAX_PLAN_WIDTH) and must be at least 1. Zero or negative widths cannot represent any plan, so construction fails; the message points at the --minimax-h3-adaln-plan-width server flag.

Source

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

        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

    def load(self, device: torch.device) -> None:
        if self.path is None:

View on GitHub (pinned to 0132848349)

Solutions

Set --minimax-h3-adaln-plan-width to at least 1 (or omit it to use the default)
To disable the plan cache path entirely, use the weight_files/None configuration rather than zeroing width

Example fix

# before
--minimax-h3-adaln-plan-width 0
# after
--minimax-h3-adaln-plan-width 64

Defensive patterns

Strategy: validation

Validate before calling

plan_width = int(args.minimax_h3_adaln_plan_width)
if plan_width < 1:
    plan_width = MINIMAX_H3_ADALN_MAX_PLAN_WIDTH  # fall back to default

Type guard

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

Prevention

Range-check numeric server flags at parse time
Keep a config test asserting all default flags satisfy constructor constraints

When it happens

Trigger: Starting with --minimax-h3-adaln-plan-width 0 (or negative), or constructing the cache with max_plan_width < 1 programmatically.

Common situations: A user sets the flag to 0 intending to disable planning instead of the supported way, or copies a config from another deployment with an incompatible value.

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

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