PaddlePaddle/PaddleOCR · error · ValueError

Make sure that when passing `sliding_window` that its value

Error message

Make sure that when passing `sliding_window` that its value is a strictly positive integer, not `{self.sliding_window}`

What it means

_MaskConverter in the PP-FormulaNet head validates its sliding_window argument at construction. sliding_window enables local (windowed) attention; a value of 0 or a negative number is meaningless, so it raises ValueError immediately.

Source

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

    and sliding window attention, which are commonly used in transformer models.

    Attributes:
        is_causal (bool): Flag indicating whether the attention mask should enforce causal masking,
                          which ensures each position can only attend to previous positions.
        sliding_window (int, optional): Size of the sliding window for local attention. If set,
                                        attention is restricted to a local window of this size.

    """

    is_causal: bool
    sliding_window: int

    def __init__(self, is_causal: bool, sliding_window=None):
        self.is_causal = is_causal
        self.sliding_window = sliding_window

        if self.sliding_window is not None and self.sliding_window <= 0:
            raise ValueError(
                f"Make sure that when passing `sliding_window` that its value is a strictly positive integer, not `{self.sliding_window}`"
            )

    @staticmethod
    def _make_causal_mask(
        input_ids_shape,
        dtype,
        past_key_values_length=0,
        sliding_window=None,
        is_export=False,
    ):
        """
        Make causal mask used for bi-directional self-attention.
        """
        bsz, tgt_len = input_ids_shape
        if is_export:
            mask = paddle.full(
                (tgt_len, tgt_len), paddle.finfo(dtype).min, dtype="float64"

View on GitHub (pinned to 2661c7c0ef)

Solutions

Set sliding_window to a strictly positive integer (e.g. 512) in the model config
Set it to null / omit it to disable windowed attention entirely
If the value is computed, clamp or validate it before it reaches the model constructor

Example fix

# before (config yml)
Head:
  sliding_window: 0
# after
Head:
  sliding_window: null   # or e.g. 512

Defensive patterns

Strategy: validation

Validate before calling

def check_sliding_window(v):
    if v is not None and (not isinstance(v, int) or v <= 0):
        raise ValueError(f'sliding_window must be a positive int or None, got {v!r}')
    return v
# check_sliding_window(cfg['Head'].get('sliding_window'))

Type guard

def valid_sliding_window(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and v > 0)

Try / catch

try:
    model = build_model(cfg)
except ValueError as e:
    if 'sliding_window' in str(e):
        cfg['Head']['sliding_window'] = None
        model = build_model(cfg)
    else:
        raise

Prevention

Use null (not 0) to disable windowed attention
LINT config: any numeric field whose name contains 'window' must be > 0 or null
When computing window size, clamp with max(1, value) or set None

When it happens

Trigger: Constructing the attention-mask converter (indirectly, when building PPFormulaNet / PPFormulaNetPlus models) with config field sliding_window set to 0, a negative int, or an expression that evaluates to <= 0.

Common situations: Trying to 'disable' sliding window by setting it to 0 instead of null/None in the config; a config default that computes window size from another parameter (e.g. max_seq_len - something) that can go non-positive for short-sequence settings.

Related errors

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