huggingface/transformers · error · ValueError

Cannot specify both size as an int, with default_to_square=T

Error message

Cannot specify both size as an int, with default_to_square=True and max_size

What it means

Thrown by convert_to_size_dict in transformers' image processing utils when the legacy `size` argument is an int while `default_to_square=True` and a `max_size` is also supplied. An int size with default_to_square means a fixed (size, size) square, which leaves no role for max_size (a cap on the longest edge when scaling the shortest edge), so the combination is ambiguous and rejected. It exists to stop image processor configs from mixing square-resize semantics with aspect-preserving-resize semantics.

Source

Thrown at src/transformers/image_processing_utils.py:561

        return False

    size_dict_keys = set(size_dict.keys())
    for allowed_keys in VALID_SIZE_DICT_KEYS:
        if size_dict_keys == allowed_keys:
            return True
    return False


def convert_to_size_dict(
    size: int | Iterable[int] | None = None,
    max_size: int | None = None,
    default_to_square: bool = True,
    height_width_order: bool = True,
) -> dict[str, int]:
    # By default, if size is an int we assume it represents a tuple of (size, size).
    if isinstance(size, int) and default_to_square:
        if max_size is not None:
            raise ValueError("Cannot specify both size as an int, with default_to_square=True and max_size")
        return {"height": size, "width": size}
    # In other configs, if size is an int and default_to_square is False, size represents the length of
    # the shortest edge after resizing.
    elif isinstance(size, int) and not default_to_square:
        size_dict = {"shortest_edge": size}
        if max_size is not None:
            size_dict["longest_edge"] = max_size
        return size_dict
    # Otherwise, if size is a tuple it's either (height, width) or (width, height)
    elif isinstance(size, (tuple, list)) and height_width_order:
        return {"height": size[0], "width": size[1]}
    elif isinstance(size, (tuple, list)) and not height_width_order:
        return {"height": size[1], "width": size[0]}
    elif size is None and max_size is not None:
        if default_to_square:
            raise ValueError("Cannot specify both default_to_square=True and max_size")
        return {"longest_edge": max_size}

View on GitHub (pinned to a597f97485)

Solutions

1. Drop max_size if you want a square resize: get_size_dict(size=224) -> {'height': 224, 'width': 224}.
2. Or pass default_to_square=False to switch to shortest/longest-edge semantics: get_size_dict(size=224, max_size=256, default_to_square=False) -> {'shortest_edge': 224, 'longest_edge': 256}.
3. Or pass size as an explicit (height, width) tuple, which bypasses the int+square branch entirely.
4. If loading from a saved preprocessor_config.json, edit it so size is either a dict like {'shortest_edge': ..., 'longest_edge': ...} or an int without max_size.

Example fix

# before
size_dict = get_size_dict(size=224, max_size=256)  # raises ValueError

# after (aspect-preserving resize)
size_dict = get_size_dict(size=224, max_size=256, default_to_square=False)
# {'shortest_edge': 224, 'longest_edge': 256}

def validate_size_kwargs(size, max_size, default_to_square=True):
    if isinstance(size, int) and default_to_square and max_size is not None:
        raise ValueError("int size + default_to_square=True cannot take max_size; drop max_size or set default_to_square=False")
    return True

When it happens

Trigger: Calling get_size_dict(size=224, max_size=256, default_to_square=True) (default), or instantiating an image processor from a config where size is an int and max_size is set (e.g. ImageProcessor(size=224, max_size=256)). Any convert_to_size_dict call where isinstance(size, int) and default_to_square and max_size is not None.

Common situations: Upgrading old feature-extractor configs that used int size + max_size, copy-pasting resize parameters between processors that use square resizing (ViT-style) and shortest-edge resizing (ConvNet-style), or passing max_size unconditionally when building configs programmatically.

Related errors

• Cannot specify both default_to_square=True and max_size
• max_size = {max_size} must be strictly greater than the requ
• Could not convert size input to size dict: {size}
• {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

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