huggingface/transformers · error · ValueError

std must have {num_channels} elements if it is an iterable,

Error message

std must have {num_channels} elements if it is an iterable, got {len(std)}

What it means

Same per-channel broadcast rule as mean: if std is a Collection its length must equal the number of image channels, else ValueError. Std is cast to the image dtype and divided against, so shape mismatch would silently broadcast wrong.

Source

Thrown at src/transformers/image_transforms.py:431

    channel_axis = get_channel_dimension_axis(image, input_data_format=input_data_format)
    num_channels = image.shape[channel_axis]

    # We cast to float32 to avoid errors that can occur when subtracting uint8 values.
    # We preserve the original dtype if it is a float type to prevent upcasting float16.
    if not np.issubdtype(image.dtype, np.floating):
        image = image.astype(np.float32)

    if isinstance(mean, Collection):
        if len(mean) != num_channels:
            raise ValueError(f"mean must have {num_channels} elements if it is an iterable, got {len(mean)}")
    else:
        mean = [mean] * num_channels
    mean = np.array(mean, dtype=image.dtype)

    if isinstance(std, Collection):
        if len(std) != num_channels:
            raise ValueError(f"std must have {num_channels} elements if it is an iterable, got {len(std)}")
    else:
        std = [std] * num_channels
    std = np.array(std, dtype=image.dtype)

    if input_data_format == ChannelDimension.LAST:
        image = (image - mean) / std
    else:
        image = ((image.T - mean) / std).T

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


def center_crop(
    image: np.ndarray,
    size: tuple[int, int],
    data_format: str | ChannelDimension | None = None,
    input_data_format: str | ChannelDimension | None = None,

View on GitHub (pinned to a597f97485)

Solutions

1. Provide one std per channel: [0.229, 0.224, 0.225] for RGB.
2. Use a scalar std for all channels.
3. Validate len(mean) == len(std) == num_channels before the call in shared preprocessing code.

Example fix

# before
img = normalize(rgb_img, mean=0.5, std=[0.225])  # 3 channels, 1 std

# after
img = normalize(rgb_img, mean=0.5, std=[0.229, 0.224, 0.225])

n = image.shape[channel_axis]
assert not isinstance(std, (list, tuple)) or len(std) == n, f"std needs {n} elements"

When it happens

Trigger: normalize(rgb_img, mean=0.5, std=[1.0]) (3 channels vs 1 std), or stats copied from a grayscale model applied to RGB.

Common situations: Mixing mean and std lists of different lengths, migrating between RGB and grayscale models, or hand-typed stat constants with a missing element.

Related errors

• mean must have {num_channels} elements if it is an iterable,
• {param_name} must have one of the following set of keys: {VA
• Unsupported channel dimension format: {channel_dim}
• The image to be converted to a PIL image contains values out
• size must have 1 or 2 elements if it is a list or tuple

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