sgl-project/sglang · error · ValueError

MiniMax H3 AdaLN cache does not exist

Error message

MiniMax H3 AdaLN cache does not exist: {self.path}

What it means

The MiniMax H3 AdaLN cache file does not exist at the configured path. Check self.path and precompute/download the cache before use.

Solutions

1. Check the path exists and is a file: ls -l <path>; fix typos or make it absolute
2. Regenerate the sidecar (build it once, then pass path afterwards)
3. Sync/ship the sidecar with the checkpoint in multi-node setups
4. Fall back to weight_files mode to rebuild on the fly

Example fix

# before
cache = MinimaxH3AdaLNCache(path="adaln_cache.safetensors")  # missing
# after
# regenerate once, then:
cache = MinimaxH3AdaLNCache(path="/abs/path/ckpt/adaln_cache.safetensors")

import os
if not os.path.isfile(cache_path):
    raise FileNotFoundError(f"generate the AdaLN sidecar first: {cache_path}")

def sidecar_ready(path: str | None) -> bool:
    return path is not None and os.path.isfile(path)

try:
    cache.load(device)
except ValueError as e:
    if "does not exist" in str(e):
        cache = MinimaxH3AdaLNCache(weight_files=shards)  # rebuild fallback
    else:
        raise

When it happens

Trigger: path points to a nonexistent file or a directory; typical with a stale sidecar path, a typo, or a sidecar that was never generated on this node.

Common situations: Distributed runs where the sidecar was built on one node and not synced, CI environments missing large cache artifacts, or a path relative to a different working directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• does not exist or is not a file
• MiniMax H3 AdaLN cache has an unsupported or missing…
• MiniMax H3 AdaLN cache has invalid timestep plans
• MiniMax H3 AdaLN cache max_plan_width must be positive; set…
• MiniMax H3 AdaLN cache max_plans must be positive

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

Appendix: source

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

        self.path = path
        self.model_variant = model_variant
        self.weight_files = weight_files
        self.max_plans = max_plans
        self.max_plan_width = max_plan_width
        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")

View on GitHub (pinned to 0132848349)