hpcaitech/Open-Sora · error · ValueError

Unknown plugin {plugin}

Error message

Unknown plugin {plugin}

What it means

This ValueError is raised by create_colossalai_plugin in opensora/utils/train.py when the plugin string in the training config is not one of the recognized colossalai plugin names (the if/elif chain over names like 'ddp', 'gemini', 'hybrid_parallel', etc., falling to the else). It exists to fail fast when building the distributed training plugin, before booster initialization.

Source

Thrown at opensora/utils/train.py:127

        plugin_kwargs["find_unused_parameters"] = True
        reduce_bucket_size_in_m = plugin_kwargs.pop("reduce_bucket_size_in_m")
        if "zero_bucket_size_in_m" not in plugin_kwargs:
            plugin_kwargs["zero_bucket_size_in_m"] = reduce_bucket_size_in_m
        plugin_kwargs.pop("cast_inputs")
        plugin_kwargs["enable_metadata_cache"] = False

        custom_policy = plugin_kwargs.pop("custom_policy", None)
        if custom_policy is not None:
            custom_policy = custom_policy()
        plugin = HybridParallelPlugin(
            custom_policy=custom_policy,
            **plugin_kwargs,
        )
        set_tensor_parallel_group(plugin.tp_group)
        set_sequence_parallel_group(plugin.sp_group)
        set_data_parallel_group(plugin.dp_group)
    else:
        raise ValueError(f"Unknown plugin {plugin}")
    return plugin


@torch.no_grad()
def update_ema(
    ema_model: torch.nn.Module, model: torch.nn.Module, optimizer=None, decay: float = 0.9999, sharded: bool = True
):
    """
    Step the EMA model towards the current model.

    Args:
        ema_model (torch.nn.Module): The EMA model.
        model (torch.nn.Module): The current model.
        optimizer (torch.optim.Optimizer): The optimizer.
        decay (float): The decay rate.
        sharded (bool): Whether the model is sharded.
    """
    ema_params = OrderedDict(ema_model.named_parameters())

View on GitHub (pinned to 7ad6a96a13)

Solutions

1. Use a plugin name the function actually supports — check the if/elif conditions in opensora/utils/train.py (e.g. "ddp" for plain distributed, or the gemini/hybrid parallel variants)
2. Match the exact spelling and case; strip stray whitespace/quotes from the config value
3. If you need ZeRO-style sharding, verify which colossalai plugin provides it in your installed colossalai version and use that name, or update OpenSora to a version supporting it

Example fix

# before
plugin_cfg = {"plugin": "deepspeed"}

# after
plugin_cfg = {"plugin": "ddp"}  # or a colossalai-supported name from create_colossalai_plugin

import inspect, opensora.utils.train as t
src = inspect.getsource(t.create_colossalai_plugin)
# simplest: whitelist the names you know are supported for your version
supported = {"ddp", "gemini", "hybrid_parallel"}
name = cfg.get("plugin", "ddp")
assert name in supported, f"plugin must be one of {supported}, got {name!r}"

def is_supported_plugin(name: str) -> bool:
    return name in {"ddp", "gemini", "hybrid_parallel"}  # verify against your version

try:
    plugin = create_colossalai_plugin(**plugin_cfg)
except ValueError:
    plugin_cfg["plugin"] = "ddp"  # fall back to plain DDP
    plugin = create_colossalai_plugin(**plugin_cfg)

When it happens

Trigger: Setting plugin: "zero2"/"zero3"/"fsdp"/"deepspeed" (or any typo like "ddp ", "DDP") in the training config read by create_colossalai_plugin. Called from get_booster and main when setting up the colossalai booster for distributed training.

Common situations: Coming from DeepSpeed/FSDP and using their plugin names in an OpenSora config; version upgrades where supported plugin names changed; typos or case errors in YAML config keys.

Related errors

• Unsupported dtype {dtype}
• Unknown optimizer: {optimizer_name}
• Invalid logging level: {level}
• block_type {block_type} is not supported
• ConvPixelUnshuffle downsample is not supported for video

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