{"record":{"id":"16bd2c40f3b440b7","repo":"open-mmlab/mmdetection","slug":"attn-mask-s-dimension-is-not-supported","errorCode":null,"errorMessage":"attn_mask's dimension {} is not supported","messagePattern":"attn_mask's dimension (.+?) is not supported","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"mmdet/models/layers/transformer/utils.py","lineNumber":581,"sourceCode":"            if attn_mask.dtype == torch.uint8:\n                warnings.warn('Byte tensor for attn_mask is deprecated.\\\n                     Use bool tensor instead.')\n                attn_mask = attn_mask.to(torch.bool)\n            if attn_mask.dim() == 2:\n                attn_mask = attn_mask.unsqueeze(0)\n                if list(attn_mask.size()) != [1, query.size(1), key.size(1)]:\n                    raise RuntimeError(\n                        'The size of the 2D attn_mask is not correct.')\n            elif attn_mask.dim() == 3:\n                if list(attn_mask.size()) != [\n                        bs * self.num_heads,\n                        query.size(1),\n                        key.size(1)\n                ]:\n                    raise RuntimeError(\n                        'The size of the 3D attn_mask is not correct.')\n            else:\n                raise RuntimeError(\n                    \"attn_mask's dimension {} is not supported\".format(\n                        attn_mask.dim()))\n        # attn_mask's dim is 3 now.\n\n        if key_padding_mask is not None and key_padding_mask.dtype == int:\n            key_padding_mask = key_padding_mask.to(torch.bool)\n\n        q = q.contiguous().view(bs, tgt_len, self.num_heads,\n                                head_dims).permute(0, 2, 1, 3).flatten(0, 1)\n        if k is not None:\n            k = k.contiguous().view(bs, src_len, self.num_heads,\n                                    head_dims).permute(0, 2, 1,\n                                                       3).flatten(0, 1)\n        if v is not None:\n            v = v.contiguous().view(bs, src_len, self.num_heads,\n                                    v_head_dims).permute(0, 2, 1,\n                                                         3).flatten(0, 1)\n","sourceCodeStart":563,"sourceCodeEnd":599,"githubUrl":"https://github.com/open-mmlab/mmdetection/blob/cfd5d3a985b0249de009b67d04f37263e11cdf3d/mmdet/models/layers/transformer/utils.py#L563-L599","documentation":"MultiheadAttention.forward_attn only supports attn_mask of dimension 2 or 3; a 1D or 4D+ mask raises RuntimeError with the offending dimension in the message.","triggerScenarios":"Passing a flattened boolean vector as attn_mask, or a 4D [bs, heads, q, k] mask from another codebase directly.","commonSituations":"Interfacing with HuggingFace-style 4D attention masks; passing key_padding-like 1D masks in the attn_mask slot.","solutions":["If 4D [bs, heads, q, k], flatten batch and heads: attn_mask.view(bs*heads, q, k)","If 1D padding mask, pass it as key_padding_mask instead of attn_mask","Reshape/choose a 2D [q, k] or 3D [bs*heads, q, k] representation"],"exampleFix":"# before\nattn_mask = torch.zeros(bs, heads, q, k)\n# after\nattn_mask = torch.zeros(bs, heads, q, k).view(bs*heads, q, k)","handlingStrategy":"validation","validationCode":"assert attn_mask.dim() in (2, 3), attn_mask.dim()","typeGuard":"def valid_attn_mask(m): return m.dim() in (2, 3)","tryCatchPattern":null,"preventionTips":["Reshape 4D HF-style masks to 3D before mmdet attention","Use key_padding_mask for padding, not attn_mask"],"tags":["mmdet","attention","attn-mask","shape-mismatch"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"cfd5d3a985b0249de009b67d04f37263e11cdf3d","analyzedAt":"2026-08-27T20:54:20.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}