What causes "Invalid conv_mode: {conv_mode}" in huggingface/pytorch-image-models?

Use conv_mode="flatten" (spatial dims folded into input dim) or "batched" (spatial slices batched) — batched is generally recommended for large spatial dims

huggingface/pytorch-image-models · error · ValueError

Invalid conv_mode: {conv_mode}

Error message

Invalid conv_mode: {conv_mode}

What it means

The Muon optimizer validates conv_mode — the strategy for mapping >2-D convolution weights to 2D matrices — and only accepts "flatten" or "batched"; anything else is rejected at construction.

Source

Thrown at timm/optim/muon.py:733

            # Simple usage - automatically uses Muon for 2D+ params, AdamW for 1D
            optimizer = Muon(model.parameters(), lr=0.02)

            # 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,

View on GitHub (pinned to 9a5261e31b)

Solutions

Use conv_mode="flatten" (spatial dims folded into input dim) or "batched" (spatial slices batched) — batched is generally recommended for large spatial dims
Remove the invalid key from your config

Example fix

# before
opt = Muon(model.parameters(), conv_mode="reshape")
# after
opt = Muon(model.parameters(), conv_mode="batched")

Defensive patterns

Strategy: validation

Validate before calling

assert cfg.conv_mode in ("flatten", "batched"), 'invalid Muon conv_mode'

Type guard

def is_valid_conv_mode(m: str) -> bool:
    return m in ("flatten", "batched")

Prevention

Validate config strings against the allowed set before constructing the optimizer
Pin the timm version whose Muon API you coded against

When it happens

Trigger: Muon(params, conv_mode='reshape') or any string other than the two supported ones.

Common situations: Guessing mode names; stale configs from a different Muon implementation (Keller Jordan's original used different knobs); copy-paste between projects.

Related errors

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