{"record":{"id":"f3d0ec898b465f94","repo":"sgl-project/sglang","slug":"minimax-h3-adaln-cache-has-an-unsupported-or-missi","errorCode":null,"errorMessage":"MiniMax H3 AdaLN cache has an unsupported or missing format_version","messagePattern":"MiniMax H3 AdaLN cache has an unsupported or missing format_version","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py","lineNumber":1180,"sourceCode":"        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\n        self.final_width = 2 * arch.hidden_size\n        # Rebuild path only: plan bit pattern -> slot, tracked on the host.\n        self._slots: dict[tuple[int, ...], int] = {}\n        self.rebuilds = 0\n\n    def load(self, device: torch.device) -> None:\n        if self.path is None:\n            self._allocate(device)\n            return\n        if not os.path.isfile(self.path):\n            raise ValueError(f\"MiniMax H3 AdaLN cache does not exist: {self.path}\")\n\n        with safe_open(self.path, framework=\"pt\", device=\"cpu\") as cache_file:\n            metadata = cache_file.metadata() or {}\n            if metadata.get(\"format_version\") != self._FORMAT_VERSION:\n                raise ValueError(\n                    \"MiniMax H3 AdaLN cache has an unsupported or missing format_version\"\n                )\n            cache_variant = metadata.get(\"model_variant\")\n            if self.model_variant is not None and cache_variant != self.model_variant:\n                raise ValueError(\n                    \"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","sourceCodeStart":1162,"sourceCodeEnd":1198,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/minimax_h3.py#L1162-L1198","documentation":"The sidecar safetensors file was opened, but its metadata lacks a format_version matching the cache class's _FORMAT_VERSION. The on-disk layout has changed (or the file is not a cache produced by this code), so tensors cannot be interpreted safely.","triggerScenarios":"Loading a sidecar built by an older/newer sglang version, a hand-crafted or corrupted safetensors file, or a different tool's file passed as the cache path.","commonSituations":"Upgrading sglang after sidecars were pre-generated, reusing cache artifacts across branches, or pointing --...adaln-cache-path at an unrelated safetensors file.","solutions":["Regenerate the AdaLN cache sidecar with the current code version","If it was built by an older version, delete it and rebuild from weight_files","Verify the file was produced by this cache builder (check its metadata keys)"],"exampleFix":"# before\ncache = MinimaxH3AdaLNCache(path=\"old/adaln_cache.safetensors\")\n# after\n# rebuild once with current version, then load by path\ncache = MinimaxH3AdaLNCache(weight_files=shards)  # rebuild path","handlingStrategy":"fallback","validationCode":"from safetensors import safe_open\nwith safe_open(path, framework=\"pt\") as f:\n    ok = (f.metadata() or {}).get(\"format_version\") == EXPECTED_FORMAT_VERSION","typeGuard":"def sidecar_version_matches(path: str, expected: str) -> bool:\n    with safe_open(path, framework=\"pt\") as f:\n        return (f.metadata() or {}).get(\"format_version\") == expected","tryCatchPattern":"try:\n    cache.load(device)\nexcept ValueError as e:\n    if \"format_version\" in str(e):\n        os.remove(cache.path)\n        rebuild_cache_from_checkpoint()  # then retry load\n    else:\n        raise","preventionTips":["Include sglang version in sidecar filenames","Invalidate/regenerate sidecars on upgrade","Never reuse cache artifacts across forks/branches"],"tags":["minimax-h3","adaln-cache","version-mismatch","safetensors"],"backgroundTag":"cache-format-version-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}