PaddlePaddle/PaddleOCR · error · ValueError

This attention mask converter is causal. Make sure to pass `

Error message

This attention mask converter is causal. Make sure to pass `key_value_length` to correctly create a causal mask.

What it means

When the PP-FormulaNet mask converter is causal and the query length exceeds the parallel step (or a sliding window is configured), it must compute past_key_values_length = key_value_length - query_length. If key_value_length was not passed, that arithmetic is impossible, so it raises.

Source

Thrown at ppocr/modeling/heads/rec_ppformulanet_head.py:194

    ):
        """
        Converts 2D attention mask to 4D attention mask by expanding mask to (bsz, head_dim=1, query_length,
        key_value_length) shape and by adding a large negative bias to not-attended positions. If attention_mask is
        causal, a causal mask will be added.
        """
        input_shape = (attention_mask_2d.shape[0], query_length)

        causal_4d_mask = None
        if use_parallel:
            step = parallel_step
        else:
            step = 1
        if (
            input_shape[-1] > step or self.sliding_window is not None
        ) and self.is_causal:

            if key_value_length is None:
                raise ValueError(
                    "This attention mask converter is causal. Make sure to pass `key_value_length` to correctly create a causal mask."
                )

            past_key_values_length = key_value_length - query_length

            if use_parallel:
                causal_4d_mask = self._make_causal_mask_parallel(
                    input_shape,
                    dtype,
                    past_key_values_length=past_key_values_length,
                    sliding_window=self.sliding_window,
                    parallel_step=parallel_step,
                    is_export=is_export,
                )
            else:
                causal_4d_mask = self._make_causal_mask(
                    input_shape,
                    dtype,

View on GitHub (pinned to 2661c7c0ef)

Solutions

Pass key_value_length explicitly to to_4d: it should equal past_key_values_length + query_length (e.g. past_key_values[0][0].shape[2] + input_shape[-1])
If you truly have no cache, pass key_value_length=query_length so past_key_values_length becomes 0
Audit custom decode loops to keep the mask call in sync with the cache bookkeeping (_update_model_kwargs_for_generation)

Example fix

# before
mask = attn_mask_converter.to_4d(attn_mask, input_shape[-1], dtype=dtype)
# after
kv_len = past_key_values[0][0].shape[2] + input_shape[-1] if past_key_values is not None else input_shape[-1]
mask = attn_mask_converter.to_4d(attn_mask, input_shape[-1], key_value_length=kv_len, dtype=dtype)

Defensive patterns

Strategy: validation

Validate before calling

def kv_length(past_key_values, q_len):
    if past_key_values is None:
        return q_len
    return past_key_values[0][0].shape[2] + q_len
# always call: converter.to_4d(mask, q_len, key_value_length=kv_length(past, q_len), dtype=dtype)

Type guard

null

Try / catch

try:
    mask = converter.to_4d(mask, q_len, dtype=dtype)
except ValueError as e:
    if 'key_value_length' in str(e):
        mask = converter.to_4d(mask, q_len, key_value_length=q_len, dtype=dtype)
    else:
        raise

Prevention

Treat key_value_length as a required argument in multi-token decoding
Centralize mask creation in one helper that also owns cache bookkeeping
Add a decode-2-steps unit test to every custom generation loop

When it happens

Trigger: Calling attn_mask_converter.to_4d(...) without key_value_length while query_length > parallel_step (usually 1, i.e. any multi-token decode step) or while sliding_window is set. Typically happens in custom forward code or a patched decode loop that omits the argument.

Common situations: Extending the decoder forward for a new generation mode and forgetting key_value_length; refactoring a step-decoding loop into a parallel one and dropping the kv-length plumbing; using cached inference where past_key_values length must be forwarded into mask creation.

Related errors

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