{"record":{"id":"e892cacafefa5b6a","repo":"sgl-project/sglang","slug":"minimax-h3-adaln-cache-has-invalid-timestep-plans","errorCode":null,"errorMessage":"MiniMax H3 AdaLN cache has invalid timestep plans","messagePattern":"MiniMax H3 AdaLN cache has invalid timestep plans","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py","lineNumber":1204,"sourceCode":"                    \"MiniMax H3 AdaLN cache model_variant does not match the loaded \"\n                    f\"variant ({cache_variant!r} != {self.model_variant!r})\"\n                )\n            plan_timesteps = cache_file.get_tensor(\"plan_timesteps\")\n            plan_lengths = cache_file.get_tensor(\"plan_lengths\")\n            block_params = cache_file.get_tensor(\"block_params\")\n            final_params = cache_file.get_tensor(\"final_params\")\n\n        expected_block_width = 6 * MINIMAX_H3_ADALN_MODALITY_NUM * self.hidden_size\n        expected_final_width = 2 * self.hidden_size\n        if (\n            plan_timesteps.dtype != _FP32_DTYPE\n            or plan_timesteps.ndim != 2\n            or plan_lengths.dtype != torch.int64\n            or plan_lengths.shape != (plan_timesteps.shape[0],)\n            or (plan_lengths < 1).any()\n            or (plan_lengths > plan_timesteps.shape[1]).any()\n        ):\n            raise ValueError(\"MiniMax H3 AdaLN cache has invalid timestep plans\")\n        if block_params.dtype != _BF16_DTYPE or block_params.shape != (\n            plan_timesteps.shape[0],\n            plan_timesteps.shape[1],\n            self.num_layers,\n            expected_block_width,\n        ):\n            raise ValueError(\"MiniMax H3 AdaLN cache has invalid block_params\")\n        if final_params.dtype != _BF16_DTYPE or final_params.shape != (\n            plan_timesteps.shape[0],\n            plan_timesteps.shape[1],\n            expected_final_width,\n        ):\n            raise ValueError(\"MiniMax H3 AdaLN cache has invalid final_params\")\n\n        self.register_buffer(\"plan_timesteps\", plan_timesteps.to(device))\n        self.register_buffer(\"plan_lengths\", plan_lengths.to(device))\n        self.register_buffer(\"block_params\", block_params.to(device))\n        self.register_buffer(\"final_params\", final_params.to(device))","sourceCodeStart":1186,"sourceCodeEnd":1222,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py#L1186-L1222","documentation":"The plan_timesteps/plan_lengths tensors inside the sidecar fail structural validation: wrong dtype (plan_lengths must be int64), wrong rank (plan_timesteps must be 2-D), plan_lengths shape not (num_plans,), or length values outside [1, max_timesteps]. The cache is corrupt or from an incompatible layout.","triggerScenarios":"load() reads plan_timesteps and plan_lengths and any of: dtype mismatch, ndim != 2, per-plan lengths < 1 or > plan_timesteps.shape[1], or plan_lengths.shape[0] != plan_timesteps.shape[0].","commonSituations":"Corrupted or truncated sidecar from an interrupted write, a file written by different builder logic, or manual editing of the safetensors cache.","solutions":["Regenerate the sidecar from the checkpoint (weight_files mode)","If it persists after regeneration, inspect the tensors with safetensors.safe_open to see which invariant breaks and report a bug","Validate sidecars with a checksum after generation to catch truncation"],"exampleFix":"# before\ncache = MinimaxH3AdaLNCache(path=\"possibly_corrupt/adaln_cache.safetensors\")\n# after\nfrom safetensors import safe_open\nwith safe_open(path, framework=\"pt\") as f:  # sanity-check tensors\n    assert f.get_tensor(\"plan_lengths\").dtype == torch.int64\ncache = MinimaxH3AdaLNCache(path=path)","handlingStrategy":"fallback","validationCode":"with safe_open(path, framework=\"pt\") as f:\n    t, l = f.get_tensor(\"plan_timesteps\"), f.get_tensor(\"plan_lengths\")\n    ok = (t.ndim == 2 and l.dtype == torch.int64\n          and l.shape == (t.shape[0],)\n          and (l >= 1).all() and (l <= t.shape[1]).all())","typeGuard":"def plans_valid(t: \"torch.Tensor\", l: \"torch.Tensor\") -> bool:\n    return (t.ndim == 2 and l.dtype == torch.int64\n            and l.shape == (t.shape[0],)\n            and bool((l >= 1).all()) and bool((l <= t.shape[1]).all()))","tryCatchPattern":"try:\n    cache.load(device)\nexcept ValueError as e:\n    if \"invalid timestep plans\" in str(e):\n        cache = MinimaxH3AdaLNCache(weight_files=shards)  # rebuild corrupt cache\n    else:\n        raise","preventionTips":["Write sidecars atomically (tmp file + rename)","Checksum sidecars after generation","Regenerate caches instead of editing them by hand"],"tags":["minimax-h3","adaln-cache","corrupt-cache","validation"],"backgroundTag":"corrupt-cache-file","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}