BerriAI/litellm · error · ValueError

Invalid size format: '{size}'. Expected format 'WIDTHxHEIGHT

Error message

Invalid size format: '{size}'. Expected format 'WIDTHxHEIGHT' (e.g., '1024x1024').

What it means

When mapping the OpenAI 'size' parameter, the handler first tries a lookup table of common sizes; otherwise it splits the string on 'x' and converts both halves to int. If that conversion raises ValueError (non-numeric component), this error is raised telling you the expected 'WIDTHxHEIGHT' format. Note the guard is partial: a size with no 'x' at all and not in the mapping is silently ignored, so only malformed 'WxH' strings with an 'x' raise.

Source

Thrown at litellm/llms/black_forest_labs/image_generation/transformation.py:137

            "1024x1024": (1024, 1024),
            "1792x1024": (1792, 1024),
            "1024x1792": (1024, 1792),
            "512x512": (512, 512),
            "256x256": (256, 256),
        }

        if size in size_mapping:
            width, height = size_mapping[size]
            optional_params["width"] = width
            optional_params["height"] = height
        elif "x" in size:
            # Parse custom size
            try:
                width, height = map(int, size.lower().split("x"))
                optional_params["width"] = width
                optional_params["height"] = height
            except ValueError:
                raise ValueError(f"Invalid size format: '{size}'. Expected format 'WIDTHxHEIGHT' (e.g., '1024x1024').")

    def validate_environment(
        self,
        headers: dict,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        api_key: str | None = None,
        api_base: str | None = None,
    ) -> dict:
        """
        Validate environment and set up headers for Black Forest Labs.

        BFL uses x-key header for authentication.
        """
        final_api_key: Final[str | None] = (
            api_key or get_secret_str("BFL_API_KEY") or get_secret_str("BLACK_FOREST_LABS_API_KEY")

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Send size as a literal 'WIDTHxHEIGHT' string of two integers, e.g. '1024x1024' or '1344x768'.
2. If sizes come from user input, validate with a regex like ^\d+x\d+$ before calling litellm.
3. Prefer the canonical sizes in the mapping table (1024x1024, etc.) to skip parsing entirely.

Example fix

# before
size = f"{width}px x {height}px"

# after
import re
assert re.fullmatch(r"\d+x\d+", f"{width}x{height}"), "size must be WxH"
size = f"{width}x{height}"

import re

def is_valid_size(size: str) -> bool:
    return bool(re.fullmatch(r"\d+x\d+", size))

def is_valid_size(size: str) -> bool:
    """True when size is WIDTHxHEIGHT with integer components."""
    parts = size.lower().split("x")
    return len(parts) == 2 and all(p.isdigit() for p in parts)

try:
    litellm.images.generate(model="bfl/flux-dev", prompt=p, size=size)
except ValueError as e:
    if "Invalid size format" in str(e):
        raise ValueError(f"user-supplied size '{size}' rejected: use WxH") from e
    raise

When it happens

Trigger: Passing size="512xABC", size="1024-X", size="1x2x3" (map of 3 values to 2 names fails), or any '<something>x<non-integer>' to a BFL image generation call.

Common situations: Building size strings dynamically from user input (e.g. f"{w}x{h}" where w/h are empty or contain units like '1024px'); copy-paste sizes from other providers using '*' or '×' separators instead of 'x'; locale issues producing comma decimals.

Related errors

• Unknown BFL image edit model: {model_name}. Supported models
• Max recursion depth {max_depth} reached while reading image
• Unsupported image input: plain string values that are not UR
• Unsupported image type: {type(image)}. Expected bytes, str (
• BFL error: {response_data['errors']}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/151f8a516e1c7be7. Report an issue: GitHub.