huggingface/transformers · error · ValueError

`rescale_factor` must be specified if `do_rescale` is `True`

Error message

`rescale_factor` must be specified if `do_rescale` is `True`.

What it means

Raised by `transformers.image_utils.validate_preprocess_arguments`, which `BaseImageProcessor.preprocess` implementations call to check do_* flag/argument pairs, when `do_rescale=True` but `rescale_factor` is None. Rescaling multiplies pixel values by the factor (typically 1/255 to move uint8 0-255 to 0-1); enabling it without a factor leaves the operation undefined, so the library refuses. It is a fail-fast contract check inside preprocess, not an environment issue.

Source

Thrown at src/transformers/image_utils.py:605

    image_std: float | list[float] | None = None,
    do_pad: bool | None = None,
    pad_size: dict[str, int] | int | None = None,
    do_center_crop: bool | None = None,
    crop_size: dict[str, int] | None = None,
    do_resize: bool | None = None,
    size: dict[str, int] | None = None,
    resample: Union["PILImageResampling", "InterpolationMode", int] | None = None,
):
    """
    Checks validity of typically used arguments in an `ImageProcessor` `preprocess` method.
    Raises `ValueError` if arguments incompatibility is caught.
    Many incompatibilities are model-specific. `do_pad` sometimes needs `size_divisor`,
    sometimes `size_divisibility`, and sometimes `size`. New models and processors added should follow
    existing arguments when possible.

    """
    if do_rescale and rescale_factor is None:
        raise ValueError("`rescale_factor` must be specified if `do_rescale` is `True`.")

    if do_pad and pad_size is None:
        # Processors pad images using different args depending on the model, so the below check is pointless
        # but we keep it for BC for now. TODO: remove in v5
        # Usually padding can be called with:
        #   - "pad_size/size" if we're padding to specific values
        #   - "size_divisor" if we're padding to any value divisible by X
        #   - "None" if we're padding to the maximum size image in batch
        raise ValueError(
            "Depending on the model, `size_divisor` or `pad_size` or `size` must be specified if `do_pad` is `True`."
        )

    if do_normalize and (image_mean is None or image_std is None):
        raise ValueError("`image_mean` and `image_std` must both be specified if `do_normalize` is `True`.")

    if do_center_crop and crop_size is None:
        raise ValueError("`crop_size` must be specified if `do_center_crop` is `True`.")

View on GitHub (pinned to a597f97485)

Solutions

1. Pass the factor with the flag: `processor(images, do_rescale=True, rescale_factor=1 / 255)`.
2. Or disable it: `processor(images, do_rescale=False)`.
3. If it fires without you passing the flag, check `processor.rescale_factor` in the saved preprocessor_config.json / model repo and re-save with the attribute set.
4. In custom processors, ensure `rescale_factor` is forwarded to the validation call and defaults to 1/255, not None.

Example fix

// before
inputs = processor(images=img, do_rescale=True, return_tensors="pt")  # ValueError

// after
inputs = processor(images=img, do_rescale=True, rescale_factor=1 / 255, return_tensors="pt")

if do_rescale:
    assert rescale_factor is not None, "do_rescale=True requires rescale_factor (typically 1/255)"

inputs = processor(images=images, do_rescale=do_rescale, rescale_factor=rescale_factor or 1 / 255)

When it happens

Trigger: Calling `processor.preprocess(images, do_rescale=True)` (or `processor(images=..., do_rescale=True)`) without passing `rescale_factor`; subclassing an image processor and overriding defaults so `rescale_factor` becomes None while `do_rescale` stays True; constructing a processor from a dict/config that sets do_rescale but drops rescale_factor.

Common situations: Toggling preprocessing flags per-call while assuming the processor's saved defaults still apply — explicitly passing `do_rescale=True` resets the paired-argument requirement in some paths; saving/loading processor configs that omit rescale_factor; custom processors forgetting to forward the argument into `validate_preprocess_arguments`.

Related errors

• Depending on the model, `size_divisor` or `pad_size` or `siz
• Unsupported format: {values}
• Invalid padding mode: {mode}
• Unsupported channel dimension: {input_data_format}
• Unrecognized image type {type(image)}

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