huggingface/transformers · error · ValueError

Unsupported data format: {input_data_format}

Error message

Unsupported data format: {input_data_format}

What it means

Raised by `transformers.image_utils.get_channel_dimension_axis` when `input_data_format` (after optional inference) is neither `ChannelDimension.FIRST` nor `ChannelDimension.LAST`. The function computes the axis index of the channel dimension (ndim-3 for first, ndim-1 for last); an unrecognized format string makes the axis undefined, so it raises. If `input_data_format` is None, inference runs first and can raise its own errors (e.g. 'Unable to infer channel dimension format').

Source

Thrown at src/transformers/image_utils.py:346

    """
    Returns the channel dimension axis of the image.

    Args:
        image (`np.ndarray`):
            The image to get the channel dimension axis of.
        input_data_format (`ChannelDimension` or `str`, *optional*):
            The channel dimension format of the image. If `None`, will infer the channel dimension from the image.

    Returns:
        The channel dimension axis of the image.
    """
    if input_data_format is None:
        input_data_format = infer_channel_dimension_format(image)
    if input_data_format == ChannelDimension.FIRST:
        return image.ndim - 3
    elif input_data_format == ChannelDimension.LAST:
        return image.ndim - 1
    raise ValueError(f"Unsupported data format: {input_data_format}")


def get_image_size(
    image: Union[np.ndarray, "PIL.Image.Image"], channel_dim: ChannelDimension | None = None
) -> tuple[int, int]:
    """
    Returns the (height, width) dimensions of the image.

    Args:
        image (`np.ndarray | PIL.Image.Image`):
            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):

View on GitHub (pinned to a597f97485)

Solutions

1. Use `ChannelDimension.FIRST` / `ChannelDimension.LAST` or exact strings 'channels_first' / 'channels_last'.
2. Normalize external values through the enum: `ChannelDimension(value)` gives a clear error for bad inputs.
3. Pass None to let the axis be inferred from the image shape.

Example fix

// before
axis = get_channel_dimension_axis(img, input_data_format="NCHW")  # ValueError

// after
from transformers.image_utils import ChannelDimension
axis = get_channel_dimension_axis(img, input_data_format=ChannelDimension.FIRST)
axis = get_channel_dimension_axis(img)  # infer

from transformers.image_utils import ChannelDimension

input_data_format = ChannelDimension(input_data_format)  # fail fast on bad strings
axis = get_channel_dimension_axis(image, input_data_format=input_data_format)

from transformers.image_utils import ChannelDimension

def is_valid_data_format(v) -> bool:
    return v in (ChannelDimension.FIRST, ChannelDimension.LAST, "channels_first", "channels_last")

When it happens

Trigger: Calling `get_channel_dimension_axis(image, 'NCHW')`, 'first', 'channels-first' (hyphen instead of underscore), or any malformed string. Also passing a lowercase enum value variant that doesn't match 'channels_first'/'channels_last'.

Common situations: Threading user- or config-supplied layout strings through custom preprocessing; conventions borrowed from other frameworks (NHWC/NCHW) that don't match transformers' enum values; typos in serialized config.

Related errors

• Unsupported channel dimension: {input_data_format}
• Unsupported data format: {channel_dim}
• 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/511f266ad0c1376d. Report an issue: GitHub.