{"record":{"id":"2dac46549a389d23","repo":"PaddlePaddle/PaddleOCR","slug":"the-mask-name-should-be-specified-for-len-sel","errorCode":null,"errorMessage":"The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for {attn_mask.size()[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_ppformulanet_head.py","lineNumber":541,"sourceCode":"                    \"`use_cache=True` is incompatible with gradient checkpointing`. Setting `use_cache=False`...\"\n                )\n                use_cache = False\n\n        # decoder layers\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        # check if head_mask/cross_attn_head_mask has a correct number of layers specified if desired\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.size()[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.size()[0]}.\"\n                    )\n        for idx, decoder_layer in enumerate(self.layers):\n            # add LayerDrop (see https://arxiv.org/abs/1909.11556 for description)\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            if self.gradient_checkpointing and self.training:\n                layer_outputs = self._gradient_checkpointing_func(\n                    decoder_layer.__call__,","sourceCodeStart":523,"sourceCodeEnd":559,"githubUrl":"https://github.com/PaddlePaddle/PaddleOCR/blob/2661c7c0ef5c613e8f93c6e93b2e052399f0f854/ppocr/modeling/heads/rec_ppformulanet_head.py#L523-L559","documentation":"head_mask and cross_attn_head_mask let you zero-out attention heads per layer; the decoder validates that the first dimension equals the number of decoder layers (len(self.layers)). A mask sized for a different layer count raises this ValueError.","triggerScenarios":"Passing head_mask (or cross_attn_head_mask) shaped (N, ...) where N != number of decoder layers — e.g. built with num_layers taken from the encoder config, from a different model size, or hardcoded from another experiment.","commonSituations":"Head-pruning experiments ported between model variants (base vs large with different num_hidden_layers); copying an HF example that builds head_mask with the encoder's layer count; reusing a saved mask tensor after changing num_layers in config.","solutions":["Build head_mask with shape[0] == model.decoder.config.num_hidden_layers, e.g. paddle.ones([num_layers, 1, 1, hidden]) style allocation","Or omit head_mask entirely (pass None) when you do not need head masking","If loading masks from checkpoints, re-allocate/resize them after any config change to num_layers"],"exampleFix":"# before\nhead_mask = paddle.ones([6, 1, 1, 1])  # but decoder has 8 layers\n# after\nn = len(model.decoder.layers)\nhead_mask = paddle.ones([n, 1, 1, 1])","handlingStrategy":"validation","validationCode":"def check_head_mask(mask, num_layers, name='head_mask'):\n    if mask is not None and mask.shape[0] != num_layers:\n        raise ValueError(f'{name} has {mask.shape[0]} entries, decoder has {num_layers} layers')\n    return mask\n# check_head_mask(head_mask, len(model.decoder.layers))","typeGuard":"def mask_matches_layers(mask, num_layers) -> bool:\n    return mask is None or mask.shape[0] == num_layers","tryCatchPattern":"null  # misconfiguration; fix construction instead of catching","preventionTips":["Derive mask shapes from len(model.decoder.layers), never hardcode","Drop head_mask (None) unless head pruning is actually used","Re-allocate masks after changing num_layers in config"],"tags":["head-mask","shape-validation","ppformulanet"],"backgroundTag":null,"analyzedSha":"2661c7c0ef5c613e8f93c6e93b2e052399f0f854","analyzedAt":"2026-08-14T20:17:30.180Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}