keras-team/keras · error · ValueError

top_padding must be >= 0. Received: top_padding={top_padding

Error message

top_padding must be >= 0. Received: top_padding={top_padding}

What it means

In pad_images, when target_height is given, the unspecified side is derived as target_height - height - given_side; if the image is already taller than the target (or the given side eats the whole budget), the derived top_padding goes negative, which is impossible, so compute_output_spec raises this specific message.

Source

Thrown at keras/src/ops/image.py:1678

            height_axis, width_axis = -2, -1
            height, width = images_shape[height_axis], images_shape[width_axis]

        target_height = self.target_height
        if target_height is None and height is not None:
            target_height = self.top_padding + height + self.bottom_padding
        target_width = self.target_width
        if target_width is None and width is not None:
            target_width = self.left_padding + width + self.right_padding

        if height is not None:
            top_padding = self.top_padding
            bottom_padding = self.bottom_padding
            if top_padding is None:
                top_padding = target_height - height - bottom_padding
            if bottom_padding is None:
                bottom_padding = target_height - height - top_padding
            if top_padding < 0:
                raise ValueError(
                    "top_padding must be >= 0. "
                    f"Received: top_padding={top_padding}"
                )
            if bottom_padding < 0:
                raise ValueError(
                    "bottom_padding must be >= 0. "
                    f"Received: bottom_padding={bottom_padding}"
                )
            if target_height < 0:
                raise ValueError(
                    "target_height must be >= 0. "
                    f"Received: target_height={target_height}"
                )

        if width is not None:
            left_padding = self.left_padding
            right_padding = self.right_padding
            if left_padding is None:

View on GitHub (pinned to 7a34a03db6)

Solutions

If the image may exceed target, branch: crop when height > target_height, pad when smaller (resize-with-pad pattern)
Raise target_height to at least image height + desired padding
Double-check height vs width ordering of the target

Example fix

# before
out = pad_images(img_h256, target_height=224, bottom_padding=0)

# after
if img.shape[0] > 224:
    out = crop_images(img, target_height=224, bottom_cropping=0)
else:
    out = pad_images(img, target_height=224, bottom_padding=0)

Defensive patterns

Strategy: validation

Validate before calling

h = images.shape[-3] if images.ndim == 4 else images.shape[0]
if target_height is not None and h is not None:
    assert target_height >= h, 'image taller than target -> use crop_images'

Type guard

def pad_target_feasible(images_height, target_height, given_side) -> bool:
    return target_height - images_height - (given_side or 0) >= 0

Try / catch

try: out = pad_images(...) except ValueError: fall back to crop_images-to-target (explicit, not silent)

Prevention

Variable-size pipelines: branch pad vs crop on image size vs target
Swapping height/width targets is a common root cause

When it happens

Trigger: pad_images(img, target_height=224, bottom_padding=0) on an image of height 256 — top_padding derives to 256-224-0 = -32 < 0.

Common situations: Fixed-size preprocessing on variable-size datasets where some images exceed target; mixing up pad and crop (wanting to shrink); wrong axis (height/width swapped) so target is compared against the wrong dimension.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/4a7da83c80356f92. Report an issue: GitHub.