sgl-project/sglang · error · ValueError

SANA-Video requires encoder_hidden_states

Error message

SANA-Video requires encoder_hidden_states

What it means

SANA-Video's forward deletes guidance and kwargs and requires encoder_hidden_states; None raises ValueError. Captions embeddings are always required, and encoder_attention_mask may be a list/tuple (first element is taken).

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/sana_video.py:520

        )
        self.layer_names = ["transformer_blocks"]

    def post_load_weights(self) -> None:
        if self.rope.freqs_cos.is_meta or self.rope.freqs_sin.is_meta:
            self.rope._init_freqs_buffers()

    def forward(
        self,
        hidden_states: torch.Tensor,
        encoder_hidden_states: torch.Tensor,
        timestep: torch.Tensor,
        guidance: torch.Tensor | None = None,
        encoder_attention_mask: torch.Tensor | None = None,
        **kwargs,
    ) -> torch.Tensor:
        del guidance, kwargs
        if encoder_hidden_states is None:
            raise ValueError("SANA-Video requires encoder_hidden_states")
        if isinstance(encoder_attention_mask, (list, tuple)):
            encoder_attention_mask = (
                encoder_attention_mask[0] if encoder_attention_mask else None
            )

        batch_size, _, num_frames, height, width = hidden_states.shape
        patch_t, patch_h, patch_w = self.patch_size
        post_patch_frames = num_frames // patch_t
        post_patch_height = height // patch_h
        post_patch_width = width // patch_w
        rotary_emb = self.rope(hidden_states)

        hidden_states = self.patch_embedding(hidden_states)
        hidden_states = hidden_states.flatten(2).transpose(1, 2)
        timestep, embedded_timestep = self.time_embed(
            timestep.flatten(), hidden_dtype=hidden_states.dtype
        )
        timestep = timestep.view(batch_size, -1, timestep.shape[-1])

View on GitHub (pinned to 0132848349)

Solutions

1. Always encode prompts (including null prompts) and pass encoder_hidden_states
2. Pass encoder_attention_mask from the tokenizer if captions are padded
3. Audit the uncond branch of your CFG pipeline

Example fix

# before
noise_pred = dit(latents, t, encoder_hidden_states=None)
# after
noise_pred = dit(latents, t, encoder_hidden_states=null_prompt_emb, encoder_attention_mask=null_mask)

assert encoder_hidden_states is not None, "SANA-Video requires caption embeddings"

When it happens

Trigger: Calling forward without caption embeddings — unconditional or mis-wired pipeline paths.

Common situations: CFG negative-prompt leg skipping the text encoder; refactors dropping caption tensors; confusion because guidance is accepted-but-ignored (del guidance) making callers assume other optional args are too.

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

• SANA forward pass requires encoder_hidden_states
• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True

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