sgl-project/sglang · error · ValueError

encoder_hidden_states must be provided.

Error message

encoder_hidden_states must be provided.

What it means

Raised by the StableDiffusion3 transformer forward when encoder_hidden_states is None. SD3 is text-conditioned; the prompt embeddings are mandatory input, unlike optional masks or guidance.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/stablediffusion3.py:110

        self.proj_out = nn.Linear(
            self.inner_dim, patch_size * patch_size * self.out_channels, bias=True
        )

        self.gradient_checkpointing = False

    def forward(
        self,
        hidden_states: torch.Tensor,
        encoder_hidden_states: torch.Tensor | None = None,
        pooled_projections: torch.Tensor | None = None,
        timestep: torch.LongTensor | None = None,
        block_controlnet_hidden_states: list | None = None,
        guidance: torch.Tensor | None = None,
        joint_attention_kwargs: dict[str, Any] | None = None,
        skip_layers: list[int] | None = None,
    ) -> torch.Tensor:
        if encoder_hidden_states is None:
            raise ValueError("encoder_hidden_states must be provided.")
        if pooled_projections is None:
            raise ValueError("pooled_projections must be provided.")

        encoder_embeddings = encoder_hidden_states

        height, width = hidden_states.shape[-2:]

        hidden_states = self.pos_embed(hidden_states)
        temb = self.time_text_embed(timestep, pooled_projections)
        encoder_embeddings = self.context_embedder(encoder_embeddings)

        skip_layer_set = set(skip_layers) if skip_layers else set()

        if block_controlnet_hidden_states is not None:
            interval_control = len(self.transformer_blocks) / len(
                block_controlnet_hidden_states
            )
        else:

View on GitHub (pinned to 0132848349)

Solutions

1. Run the prompt through the text encoders and pass the pooled/sequence embeddings as encoder_hidden_states
2. Verify the pipeline passes text_encoder_output into the transformer call

Example fix

# before
noise_pred = transformer(hidden_states=latents, timestep=t)
# after
noise_pred = transformer(hidden_states=latents, timestep=t, encoder_hidden_states=prompt_embeds)

assert encoder_hidden_states is not None, "run text encoders before DiT forward"

def has_text_conditioning(x) -> bool:
    return x is not None and getattr(x, "numel", lambda: 0)() > 0

When it happens

Trigger: Calling the SD3 transformer forward with encoder_hidden_states omitted or explicitly None.

Common situations: Adapting an unconditional generation path from a class-free model; a pipeline bug dropping the text encoder output before the DiT call.

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

• pooled_projections must be provided.
• 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/f70b191cb04d537f. Report an issue: GitHub.