huggingface/transformers · error · ValueError

Unsupported channel dimension format: {channel_dim}

Error message

Unsupported channel dimension format: {channel_dim}

What it means

After normalizing to a ChannelDimension enum, to_channel_dimension_format only knows how to transpose to FIRST (channels_first) or LAST (channels_last); anything else raises ValueError. Passing strings not equal to 'channels_first'/'channels_last', or an invalid enum value, lands in the else branch.

Source

Thrown at src/transformers/image_transforms.py:84

    """
    if not isinstance(image, np.ndarray):
        raise TypeError(f"Input image must be of type np.ndarray, got {type(image)}")

    if input_channel_dim is None:
        input_channel_dim = infer_channel_dimension_format(image)

    target_channel_dim = ChannelDimension(channel_dim)
    if input_channel_dim == target_channel_dim:
        return image

    if target_channel_dim == ChannelDimension.FIRST:
        axes = list(range(image.ndim - 3)) + [image.ndim - 1, image.ndim - 3, image.ndim - 2]
        image = image.transpose(axes)
    elif target_channel_dim == ChannelDimension.LAST:
        axes = list(range(image.ndim - 3)) + [image.ndim - 2, image.ndim - 1, image.ndim - 3]
        image = image.transpose(axes)
    else:
        raise ValueError(f"Unsupported channel dimension format: {channel_dim}")

    return image


def rescale(
    image: np.ndarray,
    scale: float,
    data_format: ChannelDimension | None = None,
    dtype: np.dtype = np.float32,
    input_data_format: str | ChannelDimension | None = None,
) -> np.ndarray:
    """
    Rescales `image` by `scale`.

    Args:
        image (`np.ndarray`):
            The image to rescale.
        scale (`float`):

View on GitHub (pinned to a597f97485)

Solutions

1. Use ChannelDimension.FIRST / ChannelDimension.LAST, or the exact strings 'channels_first' / 'channels_last'.
2. Map framework names once at the boundary: 'NCHW' -> ChannelDimension.FIRST, 'NHWC' -> ChannelDimension.LAST.
3. Validate the data_format value in your config loading before passing it down.

Example fix

# before
img = to_channel_dimension_format(img, 'NCHW')  # raises

# after
from transformers.image_utils import ChannelDimension
img = to_channel_dimension_format(img, ChannelDimension.FIRST)

from transformers.image_utils import ChannelDimension
channel_dim = ChannelDimension(channel_dim)  # raises here with a clearer signal if invalid

def is_valid_channel_dim(v) -> bool:
    try:
        ChannelDimension(v)
        return True
    except ValueError:
        return False

When it happens

Trigger: to_channel_dimension_format(image, 'channel_first') (misspelled), to_channel_dimension_format(image, 'NCHW'), or passing an int/None as channel_dim that fails ChannelDimension conversion or comparison.

Common situations: Typos in config strings, confusing framework layout names (NCHW/NHWC) with this API's vocabulary, or propagating a data_format variable that was never validated.

Related errors

• {param_name} must have one of the following set of keys: {VA
• size must have 1 or 2 elements if it is a list or tuple
• size must have 2 elements
• mean must have {num_channels} elements if it is an iterable,
• std must have {num_channels} elements if it is an iterable,

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