sgl-project/sglang · error · ValueError

encoder_hidden_states is required when encoder_key_value is

Error message

encoder_hidden_states is required when encoder_key_value is not provided.

What it means

During the forward pass of Helios attention, cross-attention K/V must come either from a precomputed encoder_key_value pair or by projecting encoder_hidden_states. If both are None there is nothing to attend to, so forward raises this ValueError.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/helios.py:402

        else:
            k = self.norm_k(k)
        k = k.unflatten(2, (self.local_num_heads, self.head_dim))
        v = v.unflatten(2, (self.local_num_heads, self.head_dim))
        return k, v

    def forward(
        self, hidden_states, encoder_hidden_states=None, encoder_key_value=None
    ):
        q, _ = self.to_q(hidden_states)
        if self.tp_rmsnorm:
            q = tensor_parallel_rms_norm(q, self.norm_q)
        else:
            q = self.norm_q(q)
        q = q.unflatten(2, (self.local_num_heads, self.head_dim))

        if encoder_key_value is None:
            if encoder_hidden_states is None:
                raise ValueError(
                    "encoder_hidden_states is required when encoder_key_value"
                    " is not provided."
                )
            encoder_key_value = self.project_kv(encoder_hidden_states)
        k, v = encoder_key_value

        x = self.attn(q, k, v)
        x = x.flatten(2)
        x, _ = self.to_out(x)
        return x


# ---------------------------------------------------------------------------
# Transformer Block
# ---------------------------------------------------------------------------


class HeliosTransformerBlock(nn.Module):

View on GitHub (pinned to 0132848349)

Solutions

Pass encoder_hidden_states (the conditioning embeddings) to forward
Or pass a precomputed encoder_key_value=(k, v) tuple if you cache cross-attention K/V outside the module
If this is a self-attention layer, route it to the self-attention path instead of the cross-attention branch

Example fix

# before
out = attn(hidden_states, encoder_key_value=None, encoder_hidden_states=None)

# after
out = attn(hidden_states, encoder_hidden_states=text_embeddings)

Defensive patterns

Strategy: validation

Validate before calling

if encoder_key_value is None:
    assert encoder_hidden_states is not None, "encoder_hidden_states required when encoder_key_value is None"

Type guard

def has_cross_inputs(encoder_key_value, encoder_hidden_states) -> bool:
    return encoder_key_value is not None or encoder_hidden_states is not None

Try / catch

try:
    out = attn(x, encoder_hidden_states=emb)
except ValueError as e:
    if 'encoder_hidden_states is required' in str(e):
        raise RuntimeError('conditioning embeddings missing from pipeline') from e
    raise

Prevention

Thread conditioning tensors through every pipeline stage explicitly
Assert required conditioning is present at pipeline entry, not inside loops
Name arguments explicitly instead of **kwargs when forwarding embeddings

When it happens

Trigger: Calling helios attention forward with encoder_key_value=None and encoder_hidden_states=None — e.g. running the DiT in cross-attention mode without passing text/image embeddings, or a pipeline step that forgot to forward the conditioning tensors.

Common situations: Building a custom sampling loop that drops the conditioning argument; self-attention layers mistakenly configured to call the cross-attention path; refactors that renamed the embeddings argument and silently pass None.

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/41171dc559a46fd7. Report an issue: GitHub.