hpcaitech/Open-Sora · error · ValueError

Unknown optimizer: {optimizer_name}

Error message

Unknown optimizer: {optimizer_name}

What it means

This ValueError is raised by create_optimizer in opensora/utils/optimizer.py when the optimizer config's "cls" field (default "HybridAdam") is not exactly "HybridAdam". The factory currently supports only HybridAdam (from colossalai), so any other optimizer name is rejected. It exists to fail fast on unknown optimizer class names in training configs.

Source

Thrown at opensora/utils/optimizer.py:25

def create_optimizer(
    model: torch.nn.Module,
    optimizer_config: dict,
) -> torch.optim.Optimizer:
    """
    Create an optimizer.

    Args:
        model (torch.nn.Module): The model to be optimized.
        optimizer_config (dict): The configuration of the optimizer.

    Returns:
        torch.optim.Optimizer: The optimizer.
    """
    optimizer_name = optimizer_config.pop("cls", "HybridAdam")
    if optimizer_name == "HybridAdam":
        optimizer_cls = HybridAdam
    else:
        raise ValueError(f"Unknown optimizer: {optimizer_name}")
    optimizer = optimizer_cls(
        filter(lambda p: p.requires_grad, model.parameters()),
        **optimizer_config,
    )
    return optimizer


def create_lr_scheduler(
    optimizer: torch.optim.Optimizer,
    num_steps_per_epoch: int,
    epochs: int = 1000,
    warmup_steps: int | None = None,
    use_cosine_scheduler: bool = False,
    initial_lr: float = 1e-6,
) -> _LRScheduler | None:
    """
    Create a learning rate scheduler.

View on GitHub (pinned to 7ad6a96a13)

Solutions

1. Set cls: "HybridAdam" (or omit cls to use the default)
2. If you need another optimizer, either construct torch.optim.AdamW(model.parameters(), **kwargs) directly instead of create_optimizer, or extend create_optimizer with a mapping like {"AdamW": torch.optim.AdamW, "HybridAdam": HybridAdam}
3. Check exact case and whitespace in the config string

Example fix

# before
optimizer = create_optimizer(model, {"cls": "AdamW", "lr": 1e-4})

# after
optimizer = torch.optim.AdamW(
    filter(lambda p: p.requires_grad, model.parameters()), lr=1e-4
)

name = optimizer_cfg.get("cls", "HybridAdam")
assert name == "HybridAdam", f"create_optimizer only supports HybridAdam, got {name!r}; build torch.optim directly otherwise"

def is_supported_optimizer(name: str) -> bool:
    return name == "HybridAdam"

try:
    opt = create_optimizer(model, cfg.copy())
except ValueError:
    opt = torch.optim.AdamW(filter(lambda p: p.requires_grad, model.parameters()), **cfg)

When it happens

Trigger: Setting optimizer: {cls: "AdamW"} or {cls: "adam"} or any name other than "HybridAdam" (exact, case-sensitive) in the training config passed to create_optimizer. Omitting cls entirely is fine and defaults to HybridAdam.

Common situations: Porting a training script from another repo that used AdamW/Adam/SGD and copying the optimizer block into OpenSora's config; case mismatches like "hybridadam"; expecting the factory to support all torch.optim optimizers.

Related errors

• Unsupported dtype {dtype}
• Unknown plugin {plugin}
• Unknown GAN loss '{self.disc_loss_type}'.
• dtype: {dtype}
• Invalid logging level: {level}

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