sgl-project/sglang · error · ValueError

pooled_projections must be provided.

Error message

pooled_projections must be provided.

What it means

Raised by the StableDiffusion3 transformer forward when pooled_projections is None. SD3 conditioning concatenates a pooled text projection with the timestep embedding, so pooled prompt embeddings are mandatory alongside encoder_hidden_states.

Source

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

        )

        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:
            interval_control = 0

View on GitHub (pinned to 0132848349)

Solutions

1. Pass the pooled prompt embeddings returned by the text encoder stack as pooled_projections
2. Check that your encode_prompt step returns (prompt_embeds, pooled_prompt_embeds) and both are forwarded

Example fix

# before
noise_pred = transformer(latents, t, encoder_hidden_states=prompt_embeds)
# after
noise_pred = transformer(latents, t, encoder_hidden_states=prompt_embeds, pooled_projections=pooled_embeds)

assert pooled_projections is not None and encoder_hidden_states is not None

def sd3_inputs_complete(enc_hs, pooled) -> bool:
    return enc_hs is not None and pooled is not None

When it happens

Trigger: Calling SD3 forward with pooled_projections omitted while passing only encoder_hidden_states.

Common situations: Pipeline code that computes prompt embeds but forgets to forward the pooled output of encode_prompt; partial port from diffusers where the arg was bundled differently.

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

• encoder_hidden_states 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/d952a3eeba1f6274. Report an issue: GitHub.