PaddlePaddle/PaddleOCR · error · ValueError

The `{mask_name}` should be specified for {len(self.layers)}

Error message

The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for {attn_mask.size()[0]}.

What it means

The export decoder validates that head_mask / cross_attn_head_mask, when given, have a leading dimension equal to the number of decoder layers (attn_mask.size()[0] == len(self.layers)). This prevents per-layer mask indexing from failing mid-loop or silently masking the wrong layers.

Source

Thrown at ppocr/modeling/heads/rec_unimernet_head.py:1788

                    "`use_cache=True` is incompatible with gradient checkpointing`. Setting `use_cache=False`..."
                )
                use_cache = False

        # decoder layers
        all_hidden_states = () if output_hidden_states else None
        all_self_attns = () if output_attentions else None
        all_cross_attentions = (
            () if (output_attentions and encoder_hidden_states is not None) else None
        )
        next_decoder_cache = () if use_cache else None

        # check if head_mask/cross_attn_head_mask has a correct number of layers specified if desired
        for attn_mask, mask_name in zip(
            [head_mask, cross_attn_head_mask], ["head_mask", "cross_attn_head_mask"]
        ):
            if attn_mask is not None:
                if attn_mask.size()[0] != len(self.layers):
                    raise ValueError(
                        f"The `{mask_name}` should be specified for {len(self.layers)} layers, but it is for"
                        f" {attn_mask.size()[0]}."
                    )

        for idx, decoder_layer in enumerate(self.layers):
            if output_hidden_states:
                all_hidden_states += (hidden_states,)
            if self.training:
                dropout_probability = paddle.rand([])
                if dropout_probability < self.layerdrop:
                    continue

            past_key_value = (
                past_key_values[idx] if past_key_values is not None else None
            )

            if self.gradient_checkpointing and self.training:
                layer_outputs = self._gradient_checkpointing_func(

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Pass head_mask=None and cross_attn_head_mask=None (default and sufficient for export)
2. Create masks with shape [len(decoder.layers), num_heads] derived from the live model object

Example fix

# before
head_mask = paddle.ones([8])  # wrong: heads only
# after
head_mask = None

if head_mask is not None:
    assert head_mask.shape[0] == len(decoder.layers), 'head_mask layer count mismatch'

def layer_mask_ok(mask, n_layers: int) -> bool:
    return mask is None or mask.size()[0] == n_layers

When it happens

Trigger: Passing head_mask sized for a different layer count during export or inference, e.g. [num_heads] instead of [num_layers, num_heads], or reusing a mask from a smaller/larger model.

Common situations: Switching UniMERNet config depth while keeping stale mask tensors; exporting with dummy inputs copied from another model variant.

Related errors

• Head mask for a single layer should be of shape {(self.num_h
• The `{mask_name}` should be specified for {len(self.layers)}
• Incorrect 4D attention_mask shape: {tuple(attention_mask.sha
• embed_dim must be divisible by num_heads (got `embed_dim`: {
• Please set inference model dir in Global.inference_model or

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/9b4d3aa875d57e28. Report an issue: GitHub.