huggingface/transformers · error · ValueError

{param_name} must have one of the following set of keys: {VA

Error message

{param_name} must have one of the following set of keys: {VALID_SIZE_DICT_KEYS}, got {size_dict.keys()}

What it means

get_size_dict validates the final dict against VALID_SIZE_DICT_KEYS and raises when the key set does not match any allowed combination (e.g. {'height','width'}, {'shortest_edge'}, {'shortest_edge','longest_edge'}, etc.). This triggers when a dict is passed directly with wrong, misspelled, or extra keys. It enforces the canonical size-dict schema introduced to remove ambiguity in image processor configs.

Source

Thrown at src/transformers/image_processing_utils.py:627

        height_width_order (`bool`, *optional*, defaults to `True`):
            If `size` is a tuple, whether it's in (height, width) or (width, height) order.
        default_to_square (`bool`, *optional*, defaults to `True`):
            If `size` is an int, whether to default to a square image or not.
    """
    if not isinstance(size, dict | SizeDict):
        size_dict = convert_to_size_dict(size, max_size, default_to_square, height_width_order)
        logger.info(
            f"{param_name} should be a dictionary with one of the following sets of keys: {VALID_SIZE_DICT_KEYS}, got {size}."
            f" Converted to {size_dict}.",
        )
    # Some remote code bypasses or overrides `_standardize_kwargs`, so handle `SizeDict` `size` here too.
    elif isinstance(size, SizeDict):
        size_dict = dict(size)
    else:
        size_dict = size

    if not is_valid_size_dict(size_dict):
        raise ValueError(
            f"{param_name} must have one of the following set of keys: {VALID_SIZE_DICT_KEYS}, got {size_dict.keys()}"
        )
    return size_dict


def select_best_resolution(original_size: tuple, possible_resolutions: list) -> tuple:
    """
    Selects the best resolution from a list of possible resolutions based on the original size.

    This is done by calculating the effective and wasted resolution for each possible resolution.

    The best fit resolution is the one that maximizes the effective resolution and minimizes the wasted resolution.

    Args:
        original_size (tuple):
            The original size of the image in the format (height, width).
        possible_resolutions (list):
            A list of possible resolutions in the format [(height1, width1), (height2, width2), ...].

View on GitHub (pinned to a597f97485)

Solutions

1. Use one of the valid key sets exactly: {'height','width'} for square/explicit resize, {'shortest_edge'} or {'shortest_edge','longest_edge'} for edge-based resize, with no extra keys.
2. Fix misspellings (e.g. 'shortestEdge' -> 'shortest_edge', 'max_size' -> 'longest_edge').
3. If unsure, pass the legacy int/tuple form and let the converter build a valid dict.
4. Inspect VALID_SIZE_DICT_KEYS (imported in transformers.image_processing_utils) for the exact allowed combinations.

Example fix

# before
size = {"shortest_edge": 224, "max_size": 256}  # invalid keys

# after
size = {"shortest_edge": 224, "longest_edge": 256}

VALID = {frozenset(k) for k in VALID_SIZE_DICT_KEYS}
assert frozenset(size_dict) in VALID, f"invalid size keys: {set(size_dict)}"

def is_valid_size_dict(d) -> bool:
    from transformers.image_processing_utils import is_valid_size_dict
    return is_valid_size_dict(d)

When it happens

Trigger: get_size_dict({'height': 224}), get_size_dict({'width': 224, 'height': 224, 'channels': 3}), get_size_dict({'shortest_edge': 224, 'max_size': 256}) (key should be longest_edge), or remote/custom processor code that bypasses _standardize_kwargs and forwards a malformed dict.

Common situations: Hand-writing preprocessor_config.json size dicts, renaming keys inconsistently when migrating from feature extractors, or third-party processor subclasses that construct their own size dicts.

Related errors

• Cannot specify both size as an int, with default_to_square=T
• Cannot specify both default_to_square=True and max_size
• Could not convert size input to size dict: {size}
• Unsupported channel dimension format: {channel_dim}
• 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/1ec48fe823098ef0. Report an issue: GitHub.