sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache model_variant does not match the load

Error message

MiniMax H3 AdaLN cache model_variant does not match the loaded variant ({cache_variant!r} != {self.model_variant!r})

What it means

The sidecar's recorded model_variant metadata disagrees with the model_variant the runtime expects (comparison only happens when self.model_variant is not None). The timestep plans are variant-specific, so loading them for a different variant would corrupt behavior.

Source

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

        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
            or plan_lengths.dtype != torch.int64
            or plan_lengths.shape != (plan_timesteps.shape[0],)
            or (plan_lengths < 1).any()
            or (plan_lengths > plan_timesteps.shape[1]).any()
        ):

View on GitHub (pinned to 0132848349)

Solutions

1. Regenerate the sidecar for the currently loaded variant
2. Point the cache path at the sidecar matching this variant (per-variant filenames/dirs)
3. If variant names changed across versions, rebuild caches after upgrading

Example fix

# before
cache = MinimaxH3AdaLNCache(path="shared/adaln_cache.safetensors", model_variant="h3-large")
# after
cache = MinimaxH3AdaLNCache(path="per_variant/h3-base/adaln_cache.safetensors", model_variant="h3-base")

with safe_open(path, framework="pt") as f:
    cached = (f.metadata() or {}).get("model_variant")
assert cached == expected_variant, f"sidecar is {cached!r}, running {expected_variant!r}"

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

When it happens

Trigger: Loading a sidecar generated for variant 'A' while the server/model runs variant 'B'; cache_variant metadata string != self.model_variant string.

Common situations: Sharing one sidecar directory across multiple MiniMax H3 model variants, renaming a variant identifier between releases, or copying checkpoint+cache partially during a variant switch.

Related errors

• --minimax-h3-adaln-cache-path requires the unquantized trans
• MiniMax H3 AdaLN cache takes exactly one of path (prebuilt s
• MiniMax H3 AdaLN cache max_plans must be positive
• MiniMax H3 AdaLN cache max_plan_width must be positive; set
• MiniMax H3 AdaLN cache does not exist: {self.path}

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