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.shape[0]}.

What it means

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.

Source

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

            if use_cache:
                print(
                    "`use_cache=True` is incompatible with gradient checkpointing`. Setting `use_cache=False`..."
                )
                use_cache = False

        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

        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.shape[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.shape[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

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

Example fix

# before
head_mask = paddle.ones([num_heads])
# after
head_mask = paddle.ones([len(decoder.layers), decoder.layers[0].self_attn.num_heads])

Defensive patterns

Strategy: validation

Validate before calling

for name, m in [('head_mask', head_mask), ('cross_attn_head_mask', cross_attn_head_mask)]:
    if m is not None:
        assert m.shape[0] == len(decoder.layers), f'{name} first dim must be {len(decoder.layers)}'

Type guard

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

Prevention

Use None head masks unless doing head-pruning experiments
Rebuild masks after any change to num_decoder_layers

When it happens

Trigger: 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.

Common situations: Changing num_decoder_layers in config while reusing an old head_mask; porting masking code from another model with a different depth.

Related errors

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