huggingface/transformers · error · ValueError

Unsupported format: {values}

Error message

Unsupported format: {values}

What it means

Raised by the nested `_expand_for_data_format` helper inside `pad()` (transformers.image_transforms.pad) when the `padding` (or `constant_values`) argument does not match any of the four shapes np.pad expansion supports. The helper accepts: a single int/float, a 1-tuple, a 2-tuple of ints, or a 2-tuple of (int, int) tuples. Anything else — a list, a 3-element tuple, or a tuple mixing types — falls through to this ValueError. This is an input-shape contract error, not an environment problem.

Source

Thrown at src/transformers/image_transforms.py:729

    """
    if input_data_format is None:
        input_data_format = infer_channel_dimension_format(image)

    def _expand_for_data_format(values):
        """
        Convert values to be in the format expected by np.pad based on the data format.
        """
        if isinstance(values, (int, float)):
            values = ((values, values), (values, values))
        elif isinstance(values, tuple) and len(values) == 1:
            values = ((values[0], values[0]), (values[0], values[0]))
        elif isinstance(values, tuple) and len(values) == 2 and isinstance(values[0], int):
            values = (values, values)
        elif isinstance(values, tuple) and len(values) == 2 and isinstance(values[0], tuple):
            pass
        else:
            raise ValueError(f"Unsupported format: {values}")

        # add 0 for channel dimension
        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:

View on GitHub (pinned to a597f97485)

Solutions

1. Convert the value to one of the accepted forms: int/float, (v,), (h, w) ints, or ((top, bottom), (left, right)) tuples — e.g. `padding = tuple(padding)` if it is a list.
2. For asymmetric padding, use the nested form: padding=((pad_top, pad_bottom), (pad_left, pad_right)).
3. If you intended np.pad semantics directly, call `np.pad` yourself on the array instead of going through this helper.
4. Check `constant_values` has the same accepted shapes when mode is 'constant'.

Example fix

// before
image = pad(img, padding=[10, 10], mode=PaddingMode.CONSTANT)  # list -> ValueError

// after
image = pad(img, padding=(10, 10), mode=PaddingMode.CONSTANT)  # tuple of ints is accepted
// or asymmetric:
image = pad(img, padding=((10, 20), (5, 5)))

from typing import Union

def valid_padding(v) -> bool:
    if isinstance(v, (int, float)):
        return True
    if isinstance(v, tuple):
        if len(v) == 1:
            return True
        if len(v) == 2 and isinstance(v[0], int) and isinstance(v[1], int):
            return True
        if len(v) == 2 and isinstance(v[0], tuple) and isinstance(v[1], tuple):
            return len(v[0]) == 2 and len(v[1]) == 2
    return False

assert valid_padding(padding), f"bad padding: {padding!r}"
# normalize lists to tuples first:
padding = tuple(padding) if isinstance(padding, list) else padding

def is_supported_padding(v) -> bool:
    return (
        isinstance(v, (int, float))
        or (isinstance(v, tuple) and (len(v) in (1, 2)))
        and not (len(v) == 2 and isinstance(v[0], float))
    )

try:
    out = pad(image, padding, mode=mode)
except ValueError as e:
    if "Unsupported format" in str(e):
        raise ValueError(f"padding must be int, (v,), (h, w), or ((t,b),(l,r)); got {padding!r}") from e
    raise

When it happens

Trigger: Calling `transformers.image_transforms.pad(image, padding=...)` (or a processor's internal padding path) with `padding` given as a Python list like [10, 10] (isinstance checks are tuple-only), a 3- or 4-element tuple like (top, right, bottom, left), a 2-tuple of floats like (10.5, 20.5) (values[0] must be int or tuple, not float), or a malformed nested tuple like ((1, 2), 3). The same helper is also applied to `constant_values`, so an invalid `constant_values` triggers it too.

Common situations: Developers copy np.pad-style padding specs (which accept lists and 4-element sequences) into a custom preprocessing pipeline that ends up in `pad()`; or they build padding dynamically (e.g. from a config dict) producing lists instead of tuples; or they pass asymmetric PIL-style 4-value padding.

Related errors

• Invalid padding mode: {mode}
• Invalid image type: {type(img)}
• Depending on the model, `size_divisor` or `pad_size` or `siz
• Input image must be of type np.ndarray, got {type(image)}
• image must be a numpy array

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