sgl-project/sglang · error · ValueError

Cosmos3 requires text_ids and text_mask to be passed

Error message

Cosmos3 requires text_ids and text_mask to be passed

What it means

Cosmos3's DiT forward is text-conditioned: it requires both text_ids (text token ids/embeddings) and text_mask (validity mask) to compute cross-attention over the conditioning. Calling forward without either raises ValueError immediately, before any compute.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/cosmos3video.py:1482

            max_text_seq_len: Real text length already computed during
                tokenization. When omitted it is derived from ``text_mask``.
            action_latents: Optional [B, T_action, D_action] noisy action
                latents for action generation.
            action_domain_ids: [B] embodiment domain IDs (0=no-action default).
            action_noisy_mask: [B, T_action, 1] where 1=noisy, 0=conditioned;
                controls which action tokens receive the timestep embedding.
                ``None`` means all tokens are noisy.
            action_fps: Frame rate for action token temporal mRoPE scaling.
                Defaults to the video fps when None.
            action_start_frame_offset: Temporal offset applied to action
                position IDs relative to the video's media_offset (default 1).

        Returns:
            [B, C, T, H, W] velocity prediction, or a tuple
            (video_pred, ...) with extra tensors when action/sound are active.
        """
        if text_ids is None or text_mask is None:
            raise ValueError("Cosmos3 requires text_ids and text_mask to be passed")

        batch_size, C, T, H, W = hidden_states.shape
        Hp, Wp, _, _ = self._pad_to_patch_size(H, W)
        if max_text_seq_len is None:
            max_text_seq_len = int(text_mask.sum(dim=1).max().item())
        if max_text_seq_len < text_ids.shape[1]:
            text_ids = text_ids[:, :max_text_seq_len]
            text_mask = text_mask[:, :max_text_seq_len]

        sound_frames = sound_latents.shape[-1] if sound_latents is not None else 0

        action_frames = 0
        if action_latents is not None:
            if self.sp_size > 1:
                raise NotImplementedError(
                    "Cosmos3 action generation does not support sequence parallelism yet"
                )
            action_frames = action_latents.shape[1]

View on GitHub (pinned to 0132848349)

Solutions

1. Pass both text_ids and text_mask derived from the tokenizer/conditioner for every forward call
2. For unconditional generation, pass an empty tensor for text_ids with a matching all-false text_mask rather than None
3. Audit the calling runtime to ensure the text-conditioning outputs are plumbed into the DiT forward signature

Example fix

# before
out = dit(hidden_states, timestep, text_ids=None, text_mask=None)
# after
out = dit(hidden_states, timestep, text_ids=text_ids, text_mask=text_mask)
# unconditional:
out = dit(hidden_states, timestep,
         text_ids=torch.zeros(B, 0, dtype=torch.long, device=hidden_states.device),
         text_mask=torch.zeros(B, 0, dtype=torch.bool, device=hidden_states.device))

assert text_ids is not None and text_mask is not None, "Cosmos3 requires text conditioning"
# or supply empties for unconditional runs:
text_ids = text_ids if text_ids is not None else torch.zeros(B, 0, dtype=torch.long, device=dev)
text_mask = text_mask if text_mask is not None else torch.zeros(B, 0, dtype=torch.bool, device=dev)

def has_text_conditioning(kwargs: dict) -> bool:
    return kwargs.get("text_ids") is not None and kwargs.get("text_mask") is not None

try:
    out = dit(...)
except ValueError as e:
    if "text_ids and text_mask" in str(e):
        raise RuntimeError("conditioner did not produce text inputs") from e
    raise

When it happens

Trigger: Invoking the Cosmos3 model/diffusion pipeline with hidden_states only, e.g. model(hidden_states, timestep) with text_ids=None or text_mask=None; or a runner that only passes an empty prompt and drops the mask.

Common situations: Building an unconditional/unprompted video generation path and assuming text inputs are optional; wiring a new scheduler/runtime that forgets to forward tokenizer outputs; empty prompt handled by skipping both args instead of passing empty tensors with an all-zero mask.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cosmos3CausalAttention requires num_attention_heads divisibl
• Cosmos3CausalAttention requires num_key_value_heads divisibl
• Cosmos3CrossAttention requires num_attention_heads divisible
• Cosmos3CrossAttention requires num_key_value_heads divisible
• Cosmos3 action generation does not support sequence parallel

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