{"record":{"id":"224cb3f6b5700803","repo":"hpcaitech/Open-Sora","slug":"contextparallelattention-should-not-be-initialized","errorCode":null,"errorMessage":"ContextParallelAttention should not be initialized directly.","messagePattern":"ContextParallelAttention should not be initialized directly\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"opensora/models/hunyuan_vae/distributed.py","lineNumber":362,"sourceCode":"        # dropout\n        hidden_states = attn.to_out[1](hidden_states)\n\n        hidden_states = gather_forward_split_backward(hidden_states, 1, sp_group)\n\n        if input_ndim == 4:\n            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)\n\n        if attn.residual_connection:\n            hidden_states = hidden_states + residual\n\n        hidden_states = hidden_states / attn.rescale_output_factor\n\n        return hidden_states\n\n\nclass ContextParallelAttention:\n    def __init__(self):\n        raise ImportError(f\"ContextParallelAttention should not be initialized directly.\")\n\n    @staticmethod\n    def from_native_module(module: Attention, process_group, *args, **kwargs) -> Attention:\n        \"\"\"\n        Convert a native RMSNorm module to colossalai layer norm module,\n        and optionally mark parameters for gradient aggregation.\n\n        Args:\n            module (nn.Module): The native RMSNorm module to be converted.\n            sp_partial_derived (bool): Whether this module's gradients are partially derived in sequence parallelism.\n\n        Returns:\n            nn.Module: The RMSNorm module.\n        \"\"\"\n\n        # Since gradients are computed using only a subset of the data,\n        # aggregation of these gradients is necessary during backpropagation.\n        # Therefore, we annotate these parameters in advance to indicate the need for gradient aggregation.","sourceCodeStart":344,"sourceCodeEnd":380,"githubUrl":"https://github.com/hpcaitech/Open-Sora/blob/7ad6a96a135feb81f755c84fb391818718f6beb2/opensora/models/hunyuan_vae/distributed.py#L344-L380","documentation":"ContextParallelAttention is a factory namespace, not an instantiable class: its __init__ deliberately raises ImportError to prevent direct construction. The intended entry point is the static factory from_native_module(module, process_group, ...), which wraps an existing diffusers Attention module for context-parallel execution.","triggerScenarios":"Writing ContextParallelAttention() instead of ContextParallelAttention.from_native_module(attn_module, sp_group). The error is by design, not an environment issue.","commonSituations":"Developers familiar with normal nn.Module wrappers instantiate the class directly when adding context parallelism to a model; copied test code that assumed a constructor.","solutions":["Use ContextParallelAttention.from_native_module(module, process_group, *args, **kwargs) to convert an existing Attention module","Pass the process group (e.g. sequence-parallel group) as the second argument","Do not attempt to bypass __init__; there is no valid direct-construction path"],"exampleFix":"# before\nattn = ContextParallelAttention()\n# after\nattn = ContextParallelAttention.from_native_module(attn, sp_group)","handlingStrategy":"validation","validationCode":"from opensora.models.hunyuan_vae.distributed import ContextParallelAttention\nattn = ContextParallelAttention.from_native_module(attn_module, sp_group)  # never ContextParallelAttention()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat ContextParallelAttention as a factory: only use from_native_module","Lint for direct instantiation of factory classes","Read the class docstring/static factory before constructing unfamiliar wrappers"],"tags":["distributed","api-misuse","factory-pattern"],"backgroundTag":"incorrect-constructor-usage","analyzedSha":"7ad6a96a135feb81f755c84fb391818718f6beb2","analyzedAt":"2026-08-28T16:58:37.171Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}