{"record":{"id":"658a71647431875f","repo":"PaddlePaddle/PaddleOCR","slug":"the-mask-name-should-be-specified-for-len-sel-658a71","errorCode":null,"errorMessage":"The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for {attn_mask.shape[0]}.","messagePattern":"The `(.+?)` should be specified for (.+?) layers, but it is for (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ppocr/modeling/heads/rec_unimernet_head.py","lineNumber":1114,"sourceCode":"            if use_cache:\n                print(\n                    \"`use_cache=True` is incompatible with gradient checkpointing`. Setting `use_cache=False`...\"\n                )\n                use_cache = False\n\n        all_hidden_states = () if output_hidden_states else None\n        all_self_attns = () if output_attentions else None\n        all_cross_attentions = (\n            () if (output_attentions and encoder_hidden_states is not None) else None\n        )\n        next_decoder_cache = () if use_cache else None\n\n        for attn_mask, mask_name in zip(\n            [head_mask, cross_attn_head_mask], [\"head_mask\", \"cross_attn_head_mask\"]\n        ):\n            if attn_mask is not None:\n                if attn_mask.shape[0] != len(self.layers):\n                    raise ValueError(\n                        f\"The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for\"\n                        f\" {attn_mask.shape[0]}.\"\n                    )\n\n        for idx, decoder_layer in enumerate(self.layers):\n            if output_hidden_states:\n                all_hidden_states += (hidden_states,)\n            if self.training:\n                dropout_probability = paddle.rand([])\n                if dropout_probability < self.layerdrop:\n                    continue\n\n            past_key_value = (\n                past_key_values[idx] if past_key_values is not None else None\n            )\n\n            if self.gradient_checkpointing and self.training:\n                layer_outputs = self._gradient_checkpointing_func(","sourceCodeStart":1096,"sourceCodeEnd":1132,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/ppocr/modeling/heads/rec_unimernet_head.py#L1096-L1132","documentation":"head_mask and cross_attn_head_mask in the UniMERNet decoder must be specified per layer: their first dimension must equal len(self.layers). The forward loop validates this before iterating so that layer_head_mask indexing never goes out of range or silently skips layers.","triggerScenarios":"Passing head_mask with first dim != number of decoder layers, e.g. a [num_heads] mask (missing the layer axis) or a mask sized for a different config depth.","commonSituations":"Changing num_decoder_layers in config while reusing an old head_mask; porting masking code from another model with a different depth.","solutions":["Pass head_mask=None and cross_attn_head_mask=None (standard usage)","Build masks as paddle.ones([num_layers, num_heads]) matching the current config's layer count"],"exampleFix":"# before\nhead_mask = paddle.ones([num_heads])\n# after\nhead_mask = paddle.ones([len(decoder.layers), decoder.layers[0].self_attn.num_heads])","handlingStrategy":"validation","validationCode":"for name, m in [('head_mask', head_mask), ('cross_attn_head_mask', cross_attn_head_mask)]:\n    if m is not None:\n        assert m.shape[0] == len(decoder.layers), f'{name} first dim must be {len(decoder.layers)}'","typeGuard":"def valid_layer_mask(mask, n_layers: int) -> bool:\n    return mask is None or mask.shape[0] == n_layers","tryCatchPattern":null,"preventionTips":["Use None head masks unless doing head-pruning experiments","Rebuild masks after any change to num_decoder_layers"],"tags":["paddle","head-mask","shape-mismatch","decoder"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}