{"record":{"id":"2378b4151cd36765","repo":"huggingface/transformers","slug":"rescale-factor-must-be-specified-if-do-rescale","errorCode":null,"errorMessage":"`rescale_factor` must be specified if `do_rescale` is `True`.","messagePattern":"`rescale_factor` must be specified if `do_rescale` is `True`\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/image_utils.py","lineNumber":605,"sourceCode":"    image_std: float | list[float] | None = None,\n    do_pad: bool | None = None,\n    pad_size: dict[str, int] | int | None = None,\n    do_center_crop: bool | None = None,\n    crop_size: dict[str, int] | None = None,\n    do_resize: bool | None = None,\n    size: dict[str, int] | None = None,\n    resample: Union[\"PILImageResampling\", \"InterpolationMode\", int] | None = None,\n):\n    \"\"\"\n    Checks validity of typically used arguments in an `ImageProcessor` `preprocess` method.\n    Raises `ValueError` if arguments incompatibility is caught.\n    Many incompatibilities are model-specific. `do_pad` sometimes needs `size_divisor`,\n    sometimes `size_divisibility`, and sometimes `size`. New models and processors added should follow\n    existing arguments when possible.\n\n    \"\"\"\n    if do_rescale and rescale_factor is None:\n        raise ValueError(\"`rescale_factor` must be specified if `do_rescale` is `True`.\")\n\n    if do_pad and pad_size is None:\n        # Processors pad images using different args depending on the model, so the below check is pointless\n        # but we keep it for BC for now. TODO: remove in v5\n        # Usually padding can be called with:\n        #   - \"pad_size/size\" if we're padding to specific values\n        #   - \"size_divisor\" if we're padding to any value divisible by X\n        #   - \"None\" if we're padding to the maximum size image in batch\n        raise ValueError(\n            \"Depending on the model, `size_divisor` or `pad_size` or `size` must be specified if `do_pad` is `True`.\"\n        )\n\n    if do_normalize and (image_mean is None or image_std is None):\n        raise ValueError(\"`image_mean` and `image_std` must both be specified if `do_normalize` is `True`.\")\n\n    if do_center_crop and crop_size is None:\n        raise ValueError(\"`crop_size` must be specified if `do_center_crop` is `True`.\")\n","sourceCodeStart":587,"sourceCodeEnd":623,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/image_utils.py#L587-L623","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","solutions":["Pass the factor with the flag: `processor(images, do_rescale=True, rescale_factor=1 / 255)`.","Or disable it: `processor(images, do_rescale=False)`.","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.","In custom processors, ensure `rescale_factor` is forwarded to the validation call and defaults to 1/255, not None."],"exampleFix":"// before\ninputs = processor(images=img, do_rescale=True, return_tensors=\"pt\")  # ValueError\n\n// after\ninputs = processor(images=img, do_rescale=True, rescale_factor=1 / 255, return_tensors=\"pt\")","handlingStrategy":"validation","validationCode":"if do_rescale:\n    assert rescale_factor is not None, \"do_rescale=True requires rescale_factor (typically 1/255)\"\n\ninputs = processor(images=images, do_rescale=do_rescale, rescale_factor=rescale_factor or 1 / 255)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass do_* flags and their paired arguments together in preprocess calls.","When toggling flags per call, mirror the processor's saved defaults from preprocessor_config.json.","For custom processors, default rescale_factor to 1/255 and forward it into validation."],"tags":["image-processing","preprocess","argument-validation","configuration"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}