{"record":{"id":"734b557b4ed6f142","repo":"sgl-project/sglang","slug":"minimax-h3-adaln-cache-takes-exactly-one-of-path","errorCode":null,"errorMessage":"MiniMax H3 AdaLN cache takes exactly one of path (prebuilt sidecar) or weight_files (rebuild from the checkpoint)","messagePattern":"MiniMax H3 AdaLN cache takes exactly one of path \\(prebuilt sidecar\\) or weight_files \\(rebuild from the checkpoint\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py","lineNumber":1146,"sourceCode":"    _FORMAT_VERSION = \"2\"\n    plan_timesteps: torch.Tensor\n    plan_lengths: torch.Tensor\n    block_params: torch.Tensor\n    final_params: torch.Tensor\n\n    def __init__(\n        self,\n        arch: MiniMaxH3DiTArchConfig,\n        *,\n        path: str | None = None,\n        model_variant: str | None = None,\n        weight_files: list[str] | None = None,\n        max_plans: int = 64,\n        max_plan_width: int = MINIMAX_H3_ADALN_MAX_PLAN_WIDTH,\n    ) -> None:\n        super().__init__()\n        if (path is None) == (weight_files is None):\n            raise ValueError(\n                \"MiniMax H3 AdaLN cache takes exactly one of path (prebuilt \"\n                \"sidecar) or weight_files (rebuild from the checkpoint)\"\n            )\n        if max_plans < 1:\n            raise ValueError(\"MiniMax H3 AdaLN cache max_plans must be positive\")\n        if max_plan_width < 1:\n            raise ValueError(\n                \"MiniMax H3 AdaLN cache max_plan_width must be positive; \"\n                \"set --minimax-h3-adaln-plan-width to at least 1\"\n            )\n        self.path = path\n        self.model_variant = model_variant\n        self.weight_files = weight_files\n        self.max_plans = max_plans\n        self.max_plan_width = max_plan_width\n        self.num_layers = arch.num_layers\n        self.hidden_size = arch.hidden_size\n        self.block_width = 6 * MINIMAX_H3_ADALN_MODALITY_NUM * arch.hidden_size","sourceCodeStart":1128,"sourceCodeEnd":1164,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py#L1128-L1164","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\ncache = MinimaxH3AdaLNCache(path=None, weight_files=None)\n# after\ncache = MinimaxH3AdaLNCache(path=\"ckpt/adaln_cache.safetensors\")\n# or\ncache = MinimaxH3AdaLNCache(weight_files=[\"ckpt/shard0.safetensors\", ...])","handlingStrategy":"validation","validationCode":"assert (path is None) != (weight_files is None), \"pass exactly one of path or weight_files\"","typeGuard":"def exactly_one_mode(path: str | None, weight_files: list[str] | None) -> bool:\n    return (path is None) != (weight_files is None)","tryCatchPattern":null,"preventionTips":["Use an Options/dataclass so only one mode field can be set","Document the two modes at the config layer"],"tags":["minimax-h3","adaln-cache","argument-validation"],"backgroundTag":"mutually-exclusive-arguments","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}