sgl-project/sglang · error · ValueError

MiniMax H3 text payload must contain positive.hidden_states

Error message

MiniMax H3 text payload must contain positive.hidden_states with at least two dimensions

What it means

When publishing native text conditioning, the payload must include payload['positive']['hidden_states'] as a tensor with ndim >= 2. This ValueError fires when 'positive' or its hidden_states is missing or the tensor is rank-1/0 — the conditioning contract for prompt_embeds is broken.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/text_encoding.py:226

    @staticmethod
    def _publish_native_text_conditioning(batch: Req) -> None:
        """Mirror H3's rich payload onto the native text-stage fields.

        H3 keeps token tags and presentation metadata in ``Req.extra``, but
        the shared TextEncodingStage contract still owns ``prompt_embeds``.
        Publishing the same tensor there preserves native verification,
        grouped-request deduplication, and downstream memory accounting
        without duplicating the embedding storage.
        """
        payload = batch.extra.get(MINIMAX_H3_TEXT_EMBEDDINGS_EXTRA_KEY)
        positive = payload.get("positive") if isinstance(payload, dict) else None
        hidden_states = (
            positive.get("hidden_states") if isinstance(positive, dict) else None
        )
        text_len = positive.get("text_len") if isinstance(positive, dict) else None
        if not isinstance(hidden_states, torch.Tensor) or hidden_states.ndim < 2:
            raise ValueError(
                "MiniMax H3 text payload must contain positive.hidden_states "
                "with at least two dimensions"
            )
        if not isinstance(text_len, int) or text_len != int(hidden_states.shape[0]):
            raise ValueError(
                "MiniMax H3 text payload positive.text_len must match the "
                "hidden-state sequence dimension"
            )
        batch.prompt_embeds = [hidden_states]
        batch.prompt_seq_lens = [[text_len]]

    def _encode_from_plan(
        self,
        batch: Req,
        plan,
        *,
        include_video_token_mask: bool = False,
    ) -> None:

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the encoder returns payload['positive']['hidden_states'] as a [seq, hidden] tensor
2. Reshape rank-1 embeddings to [1, hidden] or [seq, hidden] as appropriate before publishing
3. Use the stock MiniMaxH3Qwen3VLEncoder output format

Example fix

// before
payload = {"positive": {"hidden_states": flat_vec}}  # rank-1
// after
payload = {"positive": {"hidden_states": flat_vec.unsqueeze(0)}}  # [1, hidden]

pos = payload.get("positive") if isinstance(payload, dict) else None
hs = pos.get("hidden_states") if isinstance(pos, dict) else None
assert isinstance(hs, torch.Tensor) and hs.ndim >= 2, "bad positive.hidden_states"

def valid_positive_hidden_states(payload) -> bool:
    pos = payload.get("positive") if isinstance(payload, dict) else None
    hs = pos.get("hidden_states") if isinstance(pos, dict) else None
    return isinstance(hs, torch.Tensor) and hs.ndim >= 2

When it happens

Trigger: _publish_native_text_conditioning receives a payload dict whose 'positive' sub-dict is absent, hidden_states is None/non-tensor, or hidden_states is a flat 1-D tensor.

Common situations: A custom or older text encoder returning {'positive': None} or a flattened embedding vector; payloads built by hand or deserialized from a checkpoint losing structure.

Related errors

• MiniMax H3 text encode produced no native payload
• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• {name} must be rank {rank}, got shape={list(tensor.shape)}
• video latent spatial/time dims must be divisible by patch_si
• video token dim {int(rows.shape[-1])} != patch volume * chan

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