sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache has an unsupported or missing format_

Error message

MiniMax H3 AdaLN cache has an unsupported or missing format_version

What it means

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.

Source

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

        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:
            self._allocate(device)
            return
        if not os.path.isfile(self.path):
            raise ValueError(f"MiniMax H3 AdaLN cache does not exist: {self.path}")

        with safe_open(self.path, framework="pt", device="cpu") as cache_file:
            metadata = cache_file.metadata() or {}
            if metadata.get("format_version") != self._FORMAT_VERSION:
                raise ValueError(
                    "MiniMax H3 AdaLN cache has an unsupported or missing format_version"
                )
            cache_variant = metadata.get("model_variant")
            if self.model_variant is not None and cache_variant != self.model_variant:
                raise ValueError(
                    "MiniMax H3 AdaLN cache model_variant does not match the loaded "
                    f"variant ({cache_variant!r} != {self.model_variant!r})"
                )
            plan_timesteps = cache_file.get_tensor("plan_timesteps")
            plan_lengths = cache_file.get_tensor("plan_lengths")
            block_params = cache_file.get_tensor("block_params")
            final_params = cache_file.get_tensor("final_params")

        expected_block_width = 6 * MINIMAX_H3_ADALN_MODALITY_NUM * self.hidden_size
        expected_final_width = 2 * self.hidden_size
        if (
            plan_timesteps.dtype != _FP32_DTYPE
            or plan_timesteps.ndim != 2

View on GitHub (pinned to 0132848349)

Solutions

  1. Regenerate the AdaLN cache sidecar with the current code version
  2. If it was built by an older version, delete it and rebuild from weight_files
  3. Verify the file was produced by this cache builder (check its metadata keys)

Example fix

# before
cache = MinimaxH3AdaLNCache(path="old/adaln_cache.safetensors")
# after
# rebuild once with current version, then load by path
cache = MinimaxH3AdaLNCache(weight_files=shards)  # rebuild path
Defensive patterns

Strategy: fallback

Validate before calling

from safetensors import safe_open
with safe_open(path, framework="pt") as f:
    ok = (f.metadata() or {}).get("format_version") == EXPECTED_FORMAT_VERSION

Type guard

def sidecar_version_matches(path: str, expected: str) -> bool:
    with safe_open(path, framework="pt") as f:
        return (f.metadata() or {}).get("format_version") == expected

Try / catch

try:
    cache.load(device)
except ValueError as e:
    if "format_version" in str(e):
        os.remove(cache.path)
        rebuild_cache_from_checkpoint()  # then retry load
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: Upgrading sglang after sidecars were pre-generated, reusing cache artifacts across branches, or pointing --...adaln-cache-path at an unrelated safetensors file.

Related errors

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