{"record":{"id":"079238c4ffb28d89","repo":"sgl-project/sglang","slug":"hunyuan3d-reference-attention-requires-a-shared-ca","errorCode":null,"errorMessage":"Hunyuan3D reference attention requires a shared cache.","messagePattern":"Hunyuan3D reference attention requires a shared cache\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d_paint.py","lineNumber":101,"sourceCode":"        scale = scale.unsqueeze(1).repeat(1, num_views).reshape(-1)\n        for _ in range(output.ndim - 1):\n            scale = scale.unsqueeze(-1)\n        return scale\n\n    def forward(\n        self,\n        hidden_states: torch.Tensor,\n        encoder_hidden_states: torch.Tensor,\n        attention_mask: torch.Tensor | None = None,\n        encoder_attention_mask: torch.Tensor | None = None,\n        cross_attention_kwargs: dict[str, Any] | None = None,\n    ) -> torch.Tensor:\n        options = {} if cross_attention_kwargs is None else cross_attention_kwargs\n        num_views = int(options.get(\"num_in_batch\", 1))\n        mode = options.get(\"mode\")\n        condition_embeddings = options.get(\"condition_embed_dict\")\n        if mode is not None and not isinstance(condition_embeddings, dict):\n            raise ValueError(\"Hunyuan3D reference attention requires a shared cache.\")\n\n        normalized = self.transformer.norm1(hidden_states)\n        hidden_states = hidden_states + self.transformer.attn1(\n            normalized, attention_mask=attention_mask\n        )\n\n        if mode is not None and \"w\" in mode:\n            condition_embeddings[self.layer_name] = rearrange(\n                normalized, \"(b n) l c -> b (n l) c\", n=num_views\n            )\n\n        if mode is not None and \"r\" in mode and self.use_reference_attention:\n            if self.attn_refview is None:\n                raise RuntimeError(\"Reference attention was not initialized.\")\n            reference = condition_embeddings[self.layer_name]\n            reference = reference.unsqueeze(1).repeat(1, num_views, 1, 1)\n            reference = rearrange(reference, \"b n l c -> (b n) l c\")\n            reference_output = self.attn_refview(","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d_paint.py#L83-L119","documentation":"In Hunyuan3D Paint's transformer block forward, when a mode is supplied via cross_attention_kwargs the pipeline expects condition_embed_dict — the shared cache that stores per-layer reference embeddings — to be a dict. If mode is set but the cache is missing or not a dict, this ValueError fires because reference attention cannot proceed.","triggerScenarios":"Calling the paint UNet's block forward with cross_attention_kwargs={'mode': 'rw', ...} but no 'condition_embed_dict' key (or a non-dict value), so there is nowhere to write/read reference view embeddings.","commonSituations":"Running the paint stage with reference conditioning while a custom pipeline forgot to allocate the shared condition_embed_dict; passing mode for the generation pass without initializing the cache in the reference pass first.","solutions":["Initialize and pass condition_embed_dict as an empty dict in cross_attention_kwargs before the reference/generation passes","Run the reference forward pass first so the cache is populated, then the generation pass with mode set","Only set 'mode' in cross_attention_kwargs when you actually intend reference/multiview attention"],"exampleFix":"# before\nout = unet(sample, t, cross_attention_kwargs={\"mode\": \"rw\", \"num_in_batch\": 4})\n\n# after\nout = unet(sample, t, cross_attention_kwargs={\"mode\": \"rw\", \"num_in_batch\": 4, \"condition_embed_dict\": {}})","handlingStrategy":"validation","validationCode":"mode = cross_attention_kwargs.get('mode') if cross_attention_kwargs else None\nif mode is not None:\n    assert isinstance(cross_attention_kwargs.get('condition_embed_dict'), dict), 'condition_embed_dict required when mode is set'","typeGuard":"def has_shared_cache(cross_attention_kwargs) -> bool:\n    if not cross_attention_kwargs or cross_attention_kwargs.get('mode') is None:\n        return True\n    return isinstance(cross_attention_kwargs.get('condition_embed_dict'), dict)","tryCatchPattern":null,"preventionTips":["Allocate condition_embed_dict={} once per generation and reuse across steps","Validate cross_attention_kwargs shape at pipeline entry","Run the reference pass before the generation pass"],"tags":["runtime","diffusion","reference-attention","missing-cache"],"backgroundTag":"missing-shared-state-cache","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}