{"record":{"id":"106a1f514afc5a92","repo":"huggingface/transformers","slug":"unsupported-format-values","errorCode":null,"errorMessage":"Unsupported format: {values}","messagePattern":"Unsupported format: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_transforms.py","lineNumber":729,"sourceCode":"\n    \"\"\"\n    if input_data_format is None:\n        input_data_format = infer_channel_dimension_format(image)\n\n    def _expand_for_data_format(values):\n        \"\"\"\n        Convert values to be in the format expected by np.pad based on the data format.\n        \"\"\"\n        if isinstance(values, (int, float)):\n            values = ((values, values), (values, values))\n        elif isinstance(values, tuple) and len(values) == 1:\n            values = ((values[0], values[0]), (values[0], values[0]))\n        elif isinstance(values, tuple) and len(values) == 2 and isinstance(values[0], int):\n            values = (values, values)\n        elif isinstance(values, tuple) and len(values) == 2 and isinstance(values[0], tuple):\n            pass\n        else:\n            raise ValueError(f\"Unsupported format: {values}\")\n\n        # add 0 for channel dimension\n        values = ((0, 0), *values) if input_data_format == ChannelDimension.FIRST else (*values, (0, 0))\n\n        # Add additional padding if there's a batch dimension\n        values = ((0, 0), *values) if image.ndim == 4 else values\n        return values\n\n    padding = _expand_for_data_format(padding)\n\n    if mode == PaddingMode.CONSTANT:\n        constant_values = _expand_for_data_format(constant_values)\n        image = np.pad(image, padding, mode=\"constant\", constant_values=constant_values)\n    elif mode == PaddingMode.REFLECT:\n        image = np.pad(image, padding, mode=\"reflect\")\n    elif mode == PaddingMode.REPLICATE:\n        image = np.pad(image, padding, mode=\"edge\")\n    elif mode == PaddingMode.SYMMETRIC:","sourceCodeStart":711,"sourceCodeEnd":747,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_transforms.py#L711-L747","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","For asymmetric padding, use the nested form: padding=((pad_top, pad_bottom), (pad_left, pad_right)).","If you intended np.pad semantics directly, call `np.pad` yourself on the array instead of going through this helper.","Check `constant_values` has the same accepted shapes when mode is 'constant'."],"exampleFix":"// before\nimage = pad(img, padding=[10, 10], mode=PaddingMode.CONSTANT)  # list -> ValueError\n\n// after\nimage = pad(img, padding=(10, 10), mode=PaddingMode.CONSTANT)  # tuple of ints is accepted\n// or asymmetric:\nimage = pad(img, padding=((10, 20), (5, 5)))","handlingStrategy":"validation","validationCode":"from typing import Union\n\ndef valid_padding(v) -> bool:\n    if isinstance(v, (int, float)):\n        return True\n    if isinstance(v, tuple):\n        if len(v) == 1:\n            return True\n        if len(v) == 2 and isinstance(v[0], int) and isinstance(v[1], int):\n            return True\n        if len(v) == 2 and isinstance(v[0], tuple) and isinstance(v[1], tuple):\n            return len(v[0]) == 2 and len(v[1]) == 2\n    return False\n\nassert valid_padding(padding), f\"bad padding: {padding!r}\"\n# normalize lists to tuples first:\npadding = tuple(padding) if isinstance(padding, list) else padding","typeGuard":"def is_supported_padding(v) -> bool:\n    return (\n        isinstance(v, (int, float))\n        or (isinstance(v, tuple) and (len(v) in (1, 2)))\n        and not (len(v) == 2 and isinstance(v[0], float))\n    )","tryCatchPattern":"try:\n    out = pad(image, padding, mode=mode)\nexcept ValueError as e:\n    if \"Unsupported format\" in str(e):\n        raise ValueError(f\"padding must be int, (v,), (h, w), or ((t,b),(l,r)); got {padding!r}\") from e\n    raise","preventionTips":["Always build padding as tuples, never lists, when calling transformers padding APIs.","Centralize padding-spec construction in one helper that always emits ((top, bottom), (left, right)).","Apply the same shape checks to constant_values when using mode='constant'."],"tags":["image-processing","padding","argument-validation","numpy"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}