hpcaitech/Open-Sora · error · ImportError

ContextParallelAttention should not be initialized directly.

Error message

ContextParallelAttention should not be initialized directly.

What it means

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.

Source

Thrown at opensora/models/hunyuan_vae/distributed.py:362

        # dropout
        hidden_states = attn.to_out[1](hidden_states)

        hidden_states = gather_forward_split_backward(hidden_states, 1, sp_group)

        if input_ndim == 4:
            hidden_states = hidden_states.transpose(-1, -2).reshape(batch_size, channel, height, width)

        if attn.residual_connection:
            hidden_states = hidden_states + residual

        hidden_states = hidden_states / attn.rescale_output_factor

        return hidden_states


class ContextParallelAttention:
    def __init__(self):
        raise ImportError(f"ContextParallelAttention should not be initialized directly.")

    @staticmethod
    def from_native_module(module: Attention, process_group, *args, **kwargs) -> Attention:
        """
        Convert a native RMSNorm module to colossalai layer norm module,
        and optionally mark parameters for gradient aggregation.

        Args:
            module (nn.Module): The native RMSNorm module to be converted.
            sp_partial_derived (bool): Whether this module's gradients are partially derived in sequence parallelism.

        Returns:
            nn.Module: The RMSNorm module.
        """

        # Since gradients are computed using only a subset of the data,
        # aggregation of these gradients is necessary during backpropagation.
        # Therefore, we annotate these parameters in advance to indicate the need for gradient aggregation.

View on GitHub (pinned to 7ad6a96a13)

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

Example fix

# before
attn = ContextParallelAttention()
# after
attn = ContextParallelAttention.from_native_module(attn, sp_group)

Defensive patterns

Strategy: validation

Validate before calling

from opensora.models.hunyuan_vae.distributed import ContextParallelAttention
attn = ContextParallelAttention.from_native_module(attn_module, sp_group)  # never ContextParallelAttention()

Prevention

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

When it happens

Trigger: Writing ContextParallelAttention() instead of ContextParallelAttention.from_native_module(attn_module, sp_group). The error is by design, not an environment issue.

Common situations: 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.

Related errors

AI-assisted analysis of hpcaitech/Open-Sora@7ad6a96a13 (2026-08-28). Data as JSON: /api/errors/224cb3f6b5700803. Report an issue: GitHub.