{"record":{"id":"41171dc559a46fd7","repo":"sgl-project/sglang","slug":"encoder-hidden-states-is-required-when-encoder-key","errorCode":null,"errorMessage":"encoder_hidden_states is required when encoder_key_value is not provided.","messagePattern":"encoder_hidden_states is required when encoder_key_value is not provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/helios.py","lineNumber":402,"sourceCode":"        else:\n            k = self.norm_k(k)\n        k = k.unflatten(2, (self.local_num_heads, self.head_dim))\n        v = v.unflatten(2, (self.local_num_heads, self.head_dim))\n        return k, v\n\n    def forward(\n        self, hidden_states, encoder_hidden_states=None, encoder_key_value=None\n    ):\n        q, _ = self.to_q(hidden_states)\n        if self.tp_rmsnorm:\n            q = tensor_parallel_rms_norm(q, self.norm_q)\n        else:\n            q = self.norm_q(q)\n        q = q.unflatten(2, (self.local_num_heads, self.head_dim))\n\n        if encoder_key_value is None:\n            if encoder_hidden_states is None:\n                raise ValueError(\n                    \"encoder_hidden_states is required when encoder_key_value\"\n                    \" is not provided.\"\n                )\n            encoder_key_value = self.project_kv(encoder_hidden_states)\n        k, v = encoder_key_value\n\n        x = self.attn(q, k, v)\n        x = x.flatten(2)\n        x, _ = self.to_out(x)\n        return x\n\n\n# ---------------------------------------------------------------------------\n# Transformer Block\n# ---------------------------------------------------------------------------\n\n\nclass HeliosTransformerBlock(nn.Module):","sourceCodeStart":384,"sourceCodeEnd":420,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/helios.py#L384-L420","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nout = attn(hidden_states, encoder_key_value=None, encoder_hidden_states=None)\n\n# after\nout = attn(hidden_states, encoder_hidden_states=text_embeddings)","handlingStrategy":"validation","validationCode":"if encoder_key_value is None:\n    assert encoder_hidden_states is not None, \"encoder_hidden_states required when encoder_key_value is None\"","typeGuard":"def has_cross_inputs(encoder_key_value, encoder_hidden_states) -> bool:\n    return encoder_key_value is not None or encoder_hidden_states is not None","tryCatchPattern":"try:\n    out = attn(x, encoder_hidden_states=emb)\nexcept ValueError as e:\n    if 'encoder_hidden_states is required' in str(e):\n        raise RuntimeError('conditioning embeddings missing from pipeline') from e\n    raise","preventionTips":["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"],"tags":["runtime","attention","missing-argument","diffusion"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}