What causes "You have to specify pixel_values" in PaddlePaddle/PaddleOCR?

Pass the image tensor as the first positional arg or as pixel_values=: model(pixel_values=tensor)

PaddlePaddle/PaddleOCR · error · ValueError

You have to specify pixel_values

Error message

You have to specify pixel_values

What it means

DonutSwinModel.forward requires the pixel input tensor: if pixel_values is None it raises ValueError('You have to specify pixel_values'). All other forward args (bool_masked_pos, head_mask, output_*) have defaults; the image tensor is the one mandatory argument.

Source

Thrown at ppocr/modeling/backbones/rec_donut_swin.py:1256

                pixel_values = input_data[0]
            else:
                pixel_values = input_data
        output_attentions = (
            output_attentions
            if output_attentions is not None
            else self.config.output_attentions
        )
        output_hidden_states = (
            output_hidden_states
            if output_hidden_states is not None
            else self.config.output_hidden_states
        )
        return_dict = (
            return_dict if return_dict is not None else self.config.return_dict
        )

        if pixel_values is None:
            raise ValueError("You have to specify pixel_values")
        num_channels = pixel_values.shape[1]
        if num_channels == 1:
            pixel_values = paddle.repeat_interleave(pixel_values, repeats=3, axis=1)

        head_mask = self.get_head_mask(head_mask, len(self.config.depths))

        embedding_output, input_dimensions = self.embeddings(
            pixel_values, bool_masked_pos=bool_masked_pos
        )

        encoder_outputs = self.encoder(
            embedding_output,
            input_dimensions,
            head_mask=head_mask,
            output_attentions=output_attentions,
            output_hidden_states=output_hidden_states,
            return_dict=return_dict,
        )

View on GitHub (pinned to 2661c7c0ef)

Solutions

Pass the image tensor as the first positional arg or as pixel_values=: model(pixel_values=tensor)
Rename your batch key to pixel_values before calling forward
Guard the preprocessing: skip/raise on None samples in the dataset instead of forwarding them

Example fix

# before
out = model(images=batch_img)   # pixel_values is None -> ValueError

# after
out = model(pixel_values=batch_img)

Defensive patterns

Strategy: validation

Validate before calling

assert pixel_values is not None, 'pixel_values must be a tensor, not None'
out = model(pixel_values=pixel_values)

Type guard

import paddle

def has_pixel_values(**kwargs) -> bool:
    v = kwargs.get('pixel_values')
    return isinstance(v, paddle.Tensor)

Prevention

Use the exact keyword pixel_values (or the first positional arg) when wrapping the model
Make the dataset raise on None images instead of forwarding them
Standardize your batch dict keys with the model's expected names once, in the collate function

When it happens

Trigger: Calling model.forward() with no args, calling with keyword-arg names from another API (e.g. inputs=..., images=..., x=...) so pixel_values stays None, or a preprocessing step that returns None on failure and is passed through unchecked.

Common situations: Adapting a generic training loop that names the batch tensor differently; a dataset/dataloader yielding None for a corrupt image; wrapping the model in code that forwards **kwargs without the exact key 'pixel_values'.

Related errors

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