{"record":{"id":"b56cb0dbdcc4bb52","repo":"sgl-project/sglang","slug":"reference-attention-was-not-initialized","errorCode":null,"errorMessage":"Reference attention was not initialized.","messagePattern":"Reference attention was not initialized\\.","errorType":"panic","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d_paint.py","lineNumber":115,"sourceCode":"        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(\n                normalized, encoder_hidden_states=reference\n            )\n            reference_scale = self._broadcast_scale(\n                1.0 if self.is_turbo else options.get(\"ref_scale\", 1.0),\n                reference_output,\n                num_views,\n            )\n            hidden_states = hidden_states + reference_scale * reference_output\n\n        if num_views > 1 and self.use_multiview_attention:\n            if self.attn_multiview is None:\n                raise RuntimeError(\"Multiview attention was not initialized.\")\n            multiview = rearrange(normalized, \"(b n) l c -> b (n l) c\", n=num_views)\n            position_masks = options.get(\"position_attn_mask\")","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d_paint.py#L97-L133","documentation":"When mode contains 'r' (reference attention) and use_reference_attention is enabled, the block requires a self.attn_refview module. If it is None — i.e. reference attention was never initialized — this RuntimeError is raised before attempting the reference attention call.","triggerScenarios":"Calling forward with mode='r...' on a block where attn_refview was never created — e.g. use_reference_attention was False (or the wrong layer) at construction, or blocks were replaced without reference attention for this layer_name.","commonSituations":"Mixing a checkpoint/pipeline that enables reference attention at runtime with model blocks built with use_reference_attention=False; layer names in the cache not matching blocks that own attn_refview.","solutions":["Construct/replace the transformer blocks with use_reference_attention=True so attn_refview is initialized","Verify the layer matches one that received reference attention during _replace_transformer_blocks","Don't include 'r' in mode for blocks without reference attention"],"exampleFix":"# before\n_replace_transformer_blocks(unet, use_reference_attention=False)\nout = block(x, cross_attention_kwargs={\"mode\": \"rw\", ...})\n\n# after\n_replace_transformer_blocks(unet, use_reference_attention=True)\nout = block(x, cross_attention_kwargs={\"mode\": \"rw\", \"condition_embed_dict\": cache})","handlingStrategy":"validation","validationCode":"if 'r' in mode and getattr(block, 'use_reference_attention', False):\n    assert block.attn_refview is not None, 'attn_refview not initialized'","typeGuard":"def block_has_reference_attn(block) -> bool:\n    return getattr(block, 'use_reference_attention', False) and block.attn_refview is not None","tryCatchPattern":"try:\n    out = block(x, cross_attention_kwargs=opts)\nexcept RuntimeError as e:\n    if 'Reference attention was not initialized' in str(e):\n        opts = {**opts, 'mode': opts['mode'].replace('r', '')}\n        out = block(x, cross_attention_kwargs=opts)\n    else:\n        raise","preventionTips":["Initialize reference attention blocks before any 'r'-mode forward","Smoke-test one forward per mode after block replacement"],"tags":["runtime","initialization","reference-attention","diffusion"],"backgroundTag":"module-not-initialized","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}