{"record":{"id":"4381c0ebd471bf52","repo":"huggingface/pytorch-image-models","slug":"tensor-must-have-at-least-2-dimensions-got-tenso","errorCode":null,"errorMessage":"Tensor must have at least 2 dimensions, got {tensor.ndim}","messagePattern":"Tensor must have at least 2 dimensions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"timm/optim/muon.py","lineNumber":352,"sourceCode":"        tensor: torch.Tensor,\n        mode: str = \"flatten\",\n) -> Tuple[torch.Tensor, torch.Size]:\n    \"\"\"Reshape high-dimensional tensor for Muon processing.\n\n    Args:\n        tensor: Input tensor of shape (out, in, *spatial)\n        mode: How to handle spatial dimensions\n            - \"flatten\": Flatten spatial into output dimension (out, in*H*W)\n            - \"batched\": Batch over spatial positions (spatial_prod, out, in) for per-position orthogonalization\n\n    Returns:\n        Reshaped tensor and original shape for restoration\n    \"\"\"\n    original_shape = tensor.shape\n    if tensor.ndim == 2:\n        return tensor, original_shape\n    if tensor.ndim < 2:\n        raise ValueError(f\"Tensor must have at least 2 dimensions, got {tensor.ndim}\")\n\n    out_ch, in_ch = tensor.shape[:2]\n    if mode == \"flatten\":\n        # Flatten: (out, in, *spatial) -> (out, in * spatial_prod)\n        return tensor.reshape(out_ch, -1), original_shape\n    elif mode == \"batched\":\n        # Batched: (out, in, *spatial) -> (spatial_prod, out, in)\n        # Move spatial dimension to front so zeropower_via_newtonschulz batches over it\n        reshaped = tensor.reshape(out_ch, in_ch, -1)  # (out, in, spatial_prod)\n        reshaped = reshaped.permute(2, 0, 1)  # (spatial_prod, out, in)\n        return reshaped, original_shape\n    else:\n        raise ValueError(f\"Unknown mode: {mode}\")\n\n\ndef muon(\n        params: List[torch.Tensor],\n        grads: List[torch.Tensor],","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/huggingface/pytorch-image-models/blob/9a5261e31b3b5128526eb2658333b4c0a54464ae/timm/optim/muon.py#L334-L370","documentation":"reshape_for_muon reshapes conv/higher-dim weight matrices into 2D for the Newton–Schulz orthogonalization. It requires tensors with at least 2 dimensions; a 0-D scalar or 1-D vector (e.g. bias, LayerNorm gain) cannot be orthogonalized.","triggerScenarios":"A parameter tensor with ndim < 2 reaching the Muon update path — e.g. biases or norm weights routed into the Muon branch instead of the fallback AdamW branch, or manually calling muon()/reshape_for_muon on a vector.","commonSituations":"Misconfigured param routing (Muon optimizer normally auto-routes 1-D params to fallback); overriding use_muon/use_fallback flags incorrectly; calling the muon kernel directly on flat tensors.","solutions":["Let the optimizer route 1-D params (biases, norms) to the AdamW fallback instead of Muon","If setting per-group flags, only apply use_muon to ndim>=2 matrices","Pass a correctly shaped (out, in) matrix if calling reshape_for_muon directly"],"exampleFix":"# before\nparam_group = {'params': [model.fc1.weight, model.fc1.bias], 'use_muon': True}\n# after\nparam_group = {'params': [model.fc1.weight], 'use_muon': True}\nbias_group = {'params': [model.fc1.bias]}  # default fallback (AdamW)","handlingStrategy":"type-guard","validationCode":"muon_params = [p for p in params if p.ndim >= 2]\nfallback_params = [p for p in params if p.ndim < 2]","typeGuard":"def muon_compatible(p: torch.Tensor) -> bool:\n    return p.ndim >= 2","tryCatchPattern":null,"preventionTips":["Never route biases/norm weights into the Muon branch","Let Muon auto-route 1-D params to fallback instead of forcing use_muon"],"tags":["optimizer","muon","shape-validation","parameter-routing"],"backgroundTag":"invalid-tensor-shape","analyzedSha":"9a5261e31b3b5128526eb2658333b4c0a54464ae","analyzedAt":"2026-08-27T02:34:25.417Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}