What causes "Invalid algo: {algo}. Must be 'muon' or 'adamuon'" in huggingface/pytorch-image-models?

Use algo="muon" (default) or algo="adamuon" as needed

huggingface/pytorch-image-models · error · ValueError

Invalid algo: {algo}. Must be 'muon' or 'adamuon'

Error message

Invalid algo: {algo}. Must be 'muon' or 'adamuon'

What it means

The Muon optimizer's algo parameter selects the core update: "muon" (pure Newton–Schulz orthogonalization) or "adamuon" (Adam-style update combined with orthogonalization). Other values are rejected in __init__.

Source

Thrown at timm/optim/muon.py:735

            # Use AdaMuon algorithm for adaptive scaling
            optimizer = Muon(model.parameters(), lr=6e-4, algo="adamuon")

            # Manual control over parameter groups
            optimizer = Muon([
                {'params': weight_matrices, 'lr': 0.02},
                {'params': biases, 'use_fallback': True, 'lr': 3e-4}, # use AdamW if use_fallback=True
            ])
            ```
        """
        _validate_scalar("learning rate", lr)
        _validate_scalar("weight_decay", weight_decay)
        _validate_scalar("momentum", momentum, max_value=1.0)
        _validate_scalar("epsilon", eps)
        if conv_mode not in ["flatten", "batched"]:
            raise ValueError(f"Invalid conv_mode: {conv_mode}")
        if algo not in ["muon", "adamuon"]:
            raise ValueError(f"Invalid algo: {algo}. Must be 'muon' or 'adamuon'")

        if adamw_lr is not None:
            warnings.warn(
                "adamw_lr is deprecated, use fallback_lr_scale=adamw_lr/lr instead. "
                "adamw_lr will be removed in a future release.",
                FutureWarning,
                stacklevel=2,
            )
            if torch.is_tensor(lr):
                raise ValueError("adamw_lr is not supported with tensor lr; use fallback_lr_scale instead.")
            if lr == 0:
                raise ValueError("Cannot compute fallback_lr_scale from adamw_lr when lr=0")
            fallback_lr_scale = adamw_lr / lr

        defaults = dict(
            lr=lr,
            weight_decay=weight_decay,
            momentum=momentum,

View on GitHub (pinned to 9a5261e31b)

Solutions

Use algo="muon" (default) or algo="adamuon" as needed
If you wanted plain AdamW behavior for some params, rely on the built-in fallback branch (or use timm's AdamW) instead of an invalid algo string

Example fix

# before
opt = Muon(model.parameters(), algo="adam")
# after
opt = Muon(model.parameters(), algo="adamuon")

Defensive patterns

Strategy: validation

Validate before calling

assert cfg.algo in ("muon", "adamuon"), 'invalid Muon algo'

Type guard

def is_valid_algo(a: str) -> bool:
    return a in ("muon", "adamuon")

Prevention

Use Literal types for optimizer config fields
Rely on the fallback mechanism for AdamW-style updates instead of invalid algo strings

When it happens

Trigger: Muon(params, algo='adam') or any string besides 'muon'/'adamuon'.

Common situations: Assuming the optimizer supports a plain 'adam' mode; typos; configs from forks of the Muon codebase with different algo names.

Related errors

AI-assisted analysis of huggingface/pytorch-image-models@9a5261e31b (2026-08-27). Data as JSON: /api/errors/c02f2f79885c5863. Report an issue: GitHub.