What causes "Invalid padding mode: {mode}" in huggingface/transformers?

Use one of the four accepted values: 'constant', 'reflect', 'replicate', or 'symmetric' (or the `PaddingMode` enum members).

huggingface/transformers · error · ValueError

Invalid padding mode: {mode}

Error message

Invalid padding mode: {mode}

What it means

Raised by `transformers.image_transforms.pad()` when `mode` does not equal one of the four supported `PaddingMode` enum members: CONSTANT, REFLECT, REPLICATE, SYMMETRIC. `PaddingMode` is an `ExplicitEnum`, so raw strings 'constant', 'reflect', 'replicate', 'symmetric' also compare equal and are accepted; every other string or value reaches the else-branch and raises. This maps np.pad modes: replicate -> 'edge', symmetric -> 'symmetric'.

Source

Thrown at src/transformers/image_transforms.py:750

        values = ((0, 0), *values) if input_data_format == ChannelDimension.FIRST else (*values, (0, 0))

        # Add additional padding if there's a batch dimension
        values = ((0, 0), *values) if image.ndim == 4 else values
        return values

    padding = _expand_for_data_format(padding)

    if mode == PaddingMode.CONSTANT:
        constant_values = _expand_for_data_format(constant_values)
        image = np.pad(image, padding, mode="constant", constant_values=constant_values)
    elif mode == PaddingMode.REFLECT:
        image = np.pad(image, padding, mode="reflect")
    elif mode == PaddingMode.REPLICATE:
        image = np.pad(image, padding, mode="edge")
    elif mode == PaddingMode.SYMMETRIC:
        image = np.pad(image, padding, mode="symmetric")
    else:
        raise ValueError(f"Invalid padding mode: {mode}")

    image = to_channel_dimension_format(image, data_format, input_data_format) if data_format is not None else image
    return image


# TODO (Amy): Accept 1/3/4 channel numpy array as input and return np.array as default
def convert_to_rgb(image: ImageInput) -> ImageInput:
    """
    Converts an image to RGB format. Only converts if the image is of type PIL.Image.Image, otherwise returns the image
    as is.
    Args:
        image (Image):
            The image to convert.
    """
    requires_backends(convert_to_rgb, ["vision"])

    if not isinstance(image, PIL.Image.Image):
        return image

View on GitHub (pinned to a597f97485)

Solutions

Use one of the four accepted values: 'constant', 'reflect', 'replicate', or 'symmetric' (or the `PaddingMode` enum members).
Map np.pad names to transformers names first: 'edge' -> 'replicate', 'symmetric' -> 'symmetric'.
For unsupported modes like 'wrap'/'circular', call `np.pad` (or `torch.nn.functional.pad`) directly on the array/tensor.
Import the enum to avoid typos: `from transformers.image_transforms import PaddingMode`.

Example fix

// before
image = pad(img, (4, 4), mode="edge")     # ValueError: Invalid padding mode
image = pad(img, (4, 4), mode="circular")  # ValueError

// after
from transformers.image_transforms import PaddingMode
image = pad(img, (4, 4), mode=PaddingMode.REPLICATE)  # np.pad 'edge' equivalent
// truly unsupported modes -> use the backend directly:
image = np.pad(img, ((0,0),(4,4),(4,4)), mode="wrap")

Defensive patterns

Strategy: validation

Validate before calling

from transformers.image_transforms import PaddingMode

SUPPORTED = {m.value for m in PaddingMode}
assert isinstance(mode, PaddingMode) or mode in SUPPORTED, f"mode must be one of {SUPPORTED}, got {mode!r}"

Type guard

from transformers.image_transforms import PaddingMode

def is_supported_pad_mode(mode) -> bool:
    try:
        PaddingMode(mode)
        return True
    except ValueError:
        return False

Try / catch

try:
    out = pad(image, padding, mode=mode)
except ValueError as e:
    if "Invalid padding mode" in str(e):
        mode = "replicate" if mode == "edge" else mode  # remap foreign names
        out = pad(image, padding, mode=mode)
    else:
        raise

Prevention

Import and use the PaddingMode enum instead of raw strings.
Map np.pad/torchvision mode names at your pipeline boundary ('edge' -> 'replicate').
Reject unsupported modes (wrap, circular) early and route them to np.pad/F.pad directly.

When it happens

Trigger: Calling `pad(image, padding, mode='circular')`, `mode='edge'` (np.pad's name, not transformers'), `mode='zero'`, or a typo like 'refelct'. Also passing torchvision's padding constants or a `PaddingMode` from a different/older transformers import path whose value differs.

Common situations: Porting code from torchvision.transforms.Pad (which supports 'constant', 'edge', 'reflect', 'symmetric' — note 'edge' works there but not here) or from raw np.pad ('edge', 'wrap', 'maximum', etc.). Version changes or copy-pasted mode strings are typical causes.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/dedf5841e70ae201. Report an issue: GitHub.