huggingface/transformers · error · ValueError

Unsupported channel dimension: {input_data_format}

Error message

Unsupported channel dimension: {input_data_format}

What it means

Raised by `transformers.image_transforms.flip_channel_order()` when `input_data_format` (after inference) is neither `ChannelDimension.FIRST` ('channels_first') nor `ChannelDimension.LAST` ('channels_last'). The function reverses channel order (RGB<->BGR) by slicing along the axis implied by the format; an unknown format means the axis cannot be located, so it refuses rather than flipping the wrong axis. If `input_data_format` is None, it is first inferred with `infer_channel_dimension_format`, which can itself raise earlier.

Source

Thrown at src/transformers/image_transforms.py:808

        data_format (`ChannelDimension`, *optional*):
            The channel dimension format for the output image. Can be one of:
                - `ChannelDimension.FIRST`: image in (num_channels, height, width) format.
                - `ChannelDimension.LAST`: image in (height, width, num_channels) format.
            If unset, will use same as the input image.
        input_data_format (`ChannelDimension`, *optional*):
            The channel dimension format for the input image. Can be one of:
                - `ChannelDimension.FIRST`: image in (num_channels, height, width) format.
                - `ChannelDimension.LAST`: image in (height, width, num_channels) format.
            If unset, will use the inferred format of the input image.
    """
    input_data_format = infer_channel_dimension_format(image) if input_data_format is None else input_data_format

    if input_data_format == ChannelDimension.LAST:
        image = image[..., ::-1]
    elif input_data_format == ChannelDimension.FIRST:
        image = image[::-1, ...]
    else:
        raise ValueError(f"Unsupported channel dimension: {input_data_format}")

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


def split_to_tiles(images: "torch.Tensor", num_tiles_height: int, num_tiles_width: int) -> "torch.Tensor":
    # Split image into number of required tiles (width x height)
    batch_size, num_channels, height, width = images.size()
    images = images.view(
        batch_size,
        num_channels,
        num_tiles_height,
        height // num_tiles_height,
        num_tiles_width,
        width // num_tiles_width,
    )
    # Permute dimensions to reorder the axes

View on GitHub (pinned to a597f97485)

Solutions

1. Pass `ChannelDimension.FIRST` or `ChannelDimension.LAST`, or the exact strings 'channels_first' / 'channels_last'.
2. Leave `input_data_format=None` to let the library infer the axis from the array shape.
3. If the value comes from config/user input, normalize it against the enum before calling: `input_data_format = ChannelDimension(input_data_format)` raises a clear error for bad values.

Example fix

// before
flipped = flip_channel_order(img, input_data_format="NCHW")  # ValueError

// after
from transformers.image_utils import ChannelDimension
flipped = flip_channel_order(img, input_data_format=ChannelDimension.FIRST)
// or let it infer:
flipped = flip_channel_order(img, input_data_format=None)

from transformers.image_utils import ChannelDimension

input_data_format = ChannelDimension(input_data_format)  # raises clear error for bad values
flipped = flip_channel_order(image, input_data_format=input_data_format)

from transformers.image_utils import ChannelDimension

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

When it happens

Trigger: Calling `flip_channel_order(image, input_data_format='channel_first')` (typo, missing 's'), 'NCHW', 'first', or any string not equal to the two enum values. Also passing an explicitly invalid value so inference is skipped and the bad value reaches the else-branch directly.

Common situations: Mixing conventions across libraries: torchvision/torchaudio layouts ('NCHW'), Keras ('channels_last' works but variants don't), or older code using plain strings like 'first'/'last'. Custom preprocessing pipelines threading a user-supplied format string through without validation.

Related errors

• Unsupported data format: {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/b03f09c3c2bb93b2. Report an issue: GitHub.