{"record":{"id":"08fb873989ce677f","repo":"huggingface/transformers","slug":"unsupported-channel-dimension-format-channel-dim","errorCode":null,"errorMessage":"Unsupported channel dimension format: {channel_dim}","messagePattern":"Unsupported channel dimension format: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_transforms.py","lineNumber":84,"sourceCode":"    \"\"\"\n    if not isinstance(image, np.ndarray):\n        raise TypeError(f\"Input image must be of type np.ndarray, got {type(image)}\")\n\n    if input_channel_dim is None:\n        input_channel_dim = infer_channel_dimension_format(image)\n\n    target_channel_dim = ChannelDimension(channel_dim)\n    if input_channel_dim == target_channel_dim:\n        return image\n\n    if target_channel_dim == ChannelDimension.FIRST:\n        axes = list(range(image.ndim - 3)) + [image.ndim - 1, image.ndim - 3, image.ndim - 2]\n        image = image.transpose(axes)\n    elif target_channel_dim == ChannelDimension.LAST:\n        axes = list(range(image.ndim - 3)) + [image.ndim - 2, image.ndim - 1, image.ndim - 3]\n        image = image.transpose(axes)\n    else:\n        raise ValueError(f\"Unsupported channel dimension format: {channel_dim}\")\n\n    return image\n\n\ndef rescale(\n    image: np.ndarray,\n    scale: float,\n    data_format: ChannelDimension | None = None,\n    dtype: np.dtype = np.float32,\n    input_data_format: str | ChannelDimension | None = None,\n) -> np.ndarray:\n    \"\"\"\n    Rescales `image` by `scale`.\n\n    Args:\n        image (`np.ndarray`):\n            The image to rescale.\n        scale (`float`):","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_transforms.py#L66-L102","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use ChannelDimension.FIRST / ChannelDimension.LAST, or the exact strings 'channels_first' / 'channels_last'.","Map framework names once at the boundary: 'NCHW' -> ChannelDimension.FIRST, 'NHWC' -> ChannelDimension.LAST.","Validate the data_format value in your config loading before passing it down."],"exampleFix":"# before\nimg = to_channel_dimension_format(img, 'NCHW')  # raises\n\n# after\nfrom transformers.image_utils import ChannelDimension\nimg = to_channel_dimension_format(img, ChannelDimension.FIRST)","handlingStrategy":"validation","validationCode":"from transformers.image_utils import ChannelDimension\nchannel_dim = ChannelDimension(channel_dim)  # raises here with a clearer signal if invalid","typeGuard":"def is_valid_channel_dim(v) -> bool:\n    try:\n        ChannelDimension(v)\n        return True\n    except ValueError:\n        return False","tryCatchPattern":null,"preventionTips":["Type data_format variables as ChannelDimension, not str, across your codebase.","Map NCHW/NHWC names to ChannelDimension at one boundary function."],"tags":["image-processing","channel-dimension","valueerror","validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}