sgl-project/sglang · error · ValueError

MiniMax H3 denoise state must be a mapping

Error message

MiniMax H3 denoise state must be a mapping

What it means

The MiniMax H3 latent preparation stage reads a per-batch denoise state from batch.extra under MINIMAX_H3_DENOISE_STATE_EXTRA_KEY and requires it to be a dict. This ValueError fires when the key is missing (extra.get returns None) or holds a non-mapping value, meaning no earlier stage (or the plan-driven preparation path) populated the denoise state for this batch.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/latent_preparation.py:49

        return batch

    def run_grouped_requests(
        self,
        batches: list[Req],
        server_args: ServerArgs,
    ) -> list[Req]:
        """Preserve H3's independent per-modality RNG streams per request."""
        return [self(batch, server_args) for batch in batches]

    @staticmethod
    def _publish_native_latent_state(batch: Req) -> None:
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.constants import (
            MINIMAX_H3_DENOISE_STATE_EXTRA_KEY,
        )

        state = batch.extra.get(MINIMAX_H3_DENOISE_STATE_EXTRA_KEY)
        if not isinstance(state, dict):
            raise ValueError("MiniMax H3 denoise state must be a mapping")
        video_rows = state.get("initial_video_rows")
        audio_rows = state.get("initial_audio_rows")
        if not isinstance(video_rows, torch.Tensor) or video_rows.ndim != 2:
            raise ValueError("MiniMax H3 initial_video_rows must be a rank-2 tensor")
        if not isinstance(audio_rows, torch.Tensor) or audio_rows.ndim != 2:
            raise ValueError("MiniMax H3 initial_audio_rows must be a rank-2 tensor")

        latent_t = int(state["latent_t"])
        latent_h = int(state["latent_h"])
        latent_w = int(state["latent_w"])
        audio_t = int(state["audio_t"])
        batch.latents = video_rows
        batch.audio_latents = audio_rows
        batch.raw_latent_shape = (1, 24, latent_t, latent_h, latent_w)
        batch.raw_audio_latent_shape = (2, 32, audio_t)

    def _prepare_denoise_state_from_plan(self, batch: Req, plan) -> None:
        """Direct initial-noise materialization (t2va recipe):

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the batch passed a resolved plan so _prepare_denoise_state_from_plan populates MINIMAX_H3_DENOISE_STATE_EXTRA_KEY before latent publication
2. Check nothing upstream deletes or overwrites batch.extra[MINIMAX_H3_DENOISE_STATE_EXTRA_KEY]
3. If injecting state manually, set it to a dict containing initial_video_rows and initial_audio_rows as rank-2 tensors

Example fix

// before
batch.extra[MINIMAX_H3_DENOISE_STATE_EXTRA_KEY] = video_noise_tensor
// after
batch.extra[MINIMAX_H3_DENOISE_STATE_EXTRA_KEY] = {
    "initial_video_rows": video_noise,   # rank-2 tensor
    "initial_audio_rows": audio_noise,   # rank-2 tensor
    "latent_t": latent_t, "latent_h": latent_h, "latent_w": latent_w,
    "audio_t": audio_t,
}

state = batch.extra.get(MINIMAX_H3_DENOISE_STATE_EXTRA_KEY)
if not isinstance(state, dict):
    raise RuntimeError("run latent preparation stage (plan resolution) before forward")

def has_minimax_h3_denoise_state(batch) -> bool:
    state = batch.extra.get(MINIMAX_H3_DENOISE_STATE_EXTRA_KEY)
    return isinstance(state, dict) and "initial_video_rows" in state and "initial_audio_rows" in state

When it happens

Trigger: forward() runs _publish_native_latent_state while the batch.extra entry for the denoise state is absent or set to a non-dict (e.g. a tensor, list, or None) — typically because _prepare_denoise_state_from_plan skipped preparation or an upstream stage overwrote the key.

Common situations: A pipeline assembled without the MiniMax H3 latent preparation stage, replaying cached batches whose extra payload was serialized/deserialized into a non-dict, or another stage writing an incompatible value under the same extra key.

Related errors

• keyframe resolved_frame_index values disagree with semantic
• pipeline_cls must inherit from ComposedPipelineBase
• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 AdaLN cache has invalid timestep plans
• TP size must be positive.

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