sgl-project/sglang · error · ValueError

SANA forward pass requires encoder_hidden_states

Error message

SANA forward pass requires encoder_hidden_states

What it means

Input requirement in the SANA DiT forward: encoder_hidden_states (the text encoder outputs) are mandatory for this model; a forward call without them is a caller bug, since SANA has no text-free mode.

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)
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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


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

Appendix: 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)