sgl-project/sglang · error · ValueError

SANA forward pass requires encoder_hidden_states

Error message

SANA forward pass requires encoder_hidden_states

What it means

SANA's forward performs fail-fast validation: encoder_hidden_states (text captions embeddings) is mandatory; None raises immediately since the cross-attention has nothing to condition on.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/sana.py:580

            arch.patch_size * arch.patch_size * self.out_channels,
            bias=True,
        )

        self.layer_names = ["transformer_blocks"]

    def forward(
        self,
        hidden_states: torch.Tensor,
        encoder_hidden_states: torch.Tensor = None,
        timestep: torch.LongTensor = None,
        guidance: torch.Tensor = None,
        encoder_attention_mask: torch.Tensor = None,
        **kwargs,
    ) -> torch.Tensor:

        # Input validation - fail fast
        if encoder_hidden_states is None:
            raise ValueError("SANA forward pass requires encoder_hidden_states")

        batch_size, channels, height, width = hidden_states.shape
        p = self.patch_size
        post_patch_height = height // p
        post_patch_width = width // p

        hidden_states = _mps_safe_conv2d(self.patch_embed["proj"], hidden_states)
        # One layout conversion here prevents every downstream LayerNorm from
        # copying the transposed patch view independently.
        hidden_states = hidden_states.flatten(2).transpose(1, 2).contiguous()

        timestep_emb, embedded_timestep = self.time_embed(
            timestep, hidden_dtype=hidden_states.dtype
        )

        if isinstance(encoder_attention_mask, (list, tuple)):
            encoder_attention_mask = encoder_attention_mask[0]

View on GitHub (pinned to 0132848349)

Solutions

1. Always run the text encoder (even for null/negative prompts) and pass its embeddings
2. For CFG, pass both cond and uncond embeddings (often stacked) rather than None
3. Check pipeline code paths where captions may be empty

Example fix

# before
out = dit(hidden_states=latents, timestep=t, encoder_hidden_states=None)
# after
null_emb = text_encoder(tokenize(""), **encoder_kwargs)
out = dit(hidden_states=latents, timestep=t, encoder_hidden_states=null_emb)

assert encoder_hidden_states is not None, "SANA requires caption embeddings (encode null prompts for uncond)"

When it happens

Trigger: Calling the DiT forward with encoder_hidden_states=None (e.g. unconditional generation path or an empty-prompt path that skipped the text encoder).

Common situations: Implementing classifier-free guidance where one batch leg forgets to run the text encoder (even null prompts need embeddings); pipeline refactor dropping the caption tensor.

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-Video 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/36295b1e699bf566. Report an issue: GitHub.