huggingface/transformers · error · ValueError

Unsupported data format: {channel_dim}

Error message

Unsupported data format: {channel_dim}

What it means

Raised by `transformers.image_utils.get_image_size` when `channel_dim` (after optional inference from the array shape) is neither `ChannelDimension.FIRST` nor `ChannelDimension.LAST`. The function returns (height, width) by indexing shape[-2:]/shape[-3:-1] depending on the layout; an unknown layout makes the indices ambiguous. PIL inputs return early via `image.size` and never hit this.

Source

Thrown at src/transformers/image_utils.py:375

            The image to get the dimensions of.
        channel_dim (`ChannelDimension`, *optional*):
            Which dimension the channel dimension is in. If `None`, will infer the channel dimension from the image.

    Returns:
        A tuple of the image's height and width.
    """
    if isinstance(image, PIL.Image.Image):
        return image.size

    if channel_dim is None:
        channel_dim = infer_channel_dimension_format(image)

    if channel_dim == ChannelDimension.FIRST:
        return image.shape[-2], image.shape[-1]
    elif channel_dim == ChannelDimension.LAST:
        return image.shape[-3], image.shape[-2]
    else:
        raise ValueError(f"Unsupported data format: {channel_dim}")


def get_image_size_for_max_height_width(
    image_size: tuple[int, int],
    max_height: int,
    max_width: int,
) -> tuple[int, int]:
    """
    Computes the output image size given the input image and the maximum allowed height and width. Keep aspect ratio.
    Important, even if image_height < max_height and image_width < max_width, the image will be resized
    to at least one of the edges be equal to max_height or max_width.

    For example:
        - input_size: (100, 200), max_height: 50, max_width: 50 -> output_size: (25, 50)
        - input_size: (100, 200), max_height: 200, max_width: 500 -> output_size: (200, 400)

    Args:
        image_size (`tuple[int, int]`):

View on GitHub (pinned to a597f97485)

Solutions

1. Pass `ChannelDimension.FIRST`/`ChannelDimension.LAST` or the exact strings 'channels_first'/'channels_last'.
2. Validate external strings once at the boundary: `ChannelDimension(value)`.
3. Pass None to infer from shape — but ensure the shape makes inference possible (1/3 channels at an end axis).

Example fix

// before
h, w = get_image_size(arr, channel_dim="HWC")  # ValueError

// after
from transformers.image_utils import ChannelDimension
h, w = get_image_size(arr, channel_dim=ChannelDimension.LAST)
h, w = get_image_size(arr)  # infer

from transformers.image_utils import ChannelDimension

if channel_dim is not None:
    channel_dim = ChannelDimension(channel_dim)  # clear error on bad value
h, w = get_image_size(image, channel_dim=channel_dim)

from transformers.image_utils import ChannelDimension

def is_valid_channel_dim(v) -> bool:
    return v is None or v in (ChannelDimension.FIRST, ChannelDimension.LAST, "channels_first", "channels_last")

When it happens

Trigger: Calling `get_image_size(np_img, channel_dim='CHW')`, 'channels-first', 'first', or any string that is not exactly 'channels_first'/'channels_last'. Passing None lets inference run, which can instead raise 'Unable to infer channel dimension format' or 'Unsupported number of image dimensions'.

Common situations: Custom pipelines passing layout shorthand (CHW/HWC/NCHW) borrowed from other frameworks; config files with free-text layout fields; typos like 'channels-first'.

Related errors

• Unsupported channel dimension: {input_data_format}
• Unsupported data format: {input_data_format}
• Invalid padding mode: {mode}
• Invalid channel dimension format: {input_data_format}
• Input image must be of type np.ndarray, got {type(image)}

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