sgl-project/sglang · error · ValueError

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

Error message

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

What it means

The AdaLN cache was constructed in sidecar mode (path set), but load() finds no regular file at that path. The cache cannot be hydrated, so weight loading (post_load_weights) aborts.

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)

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

• --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 has an unsupported or missing format_

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