BerriAI/litellm · error · ValueError

Invalid size format: ' '. Expected format 'WIDTHxHEIGHT'…

Error message

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

What it means

BFL's transformation maps the OpenAI size string to explicit width/height. Known presets are looked up first; otherwise the string is split on 'x' and both halves parsed with int(). If the split yields non-integer parts (or not exactly two), this ValueError is raised. Note the sibling gap: a size string with no 'x' at all (e.g. 'large') is silently ignored and BFL defaults are used — this error only fires when 'x' is present but parsing fails.

Solutions

Use the exact 'WIDTHxHEIGHT' decimal format, e.g. '1024x1024'.
Prefer preset strings already in the mapping (1024x1024, etc.) to skip parsing entirely.
Validate/construct size with a regex before calling so a bad value never reaches the mapper.

Example fix

# before
litellm.image_generation(
    model="black_forest_labs/flux-pro-1.1",
    prompt="a cat",
    size=f"{width}x{height}",  # height accidentally '' -> ValueError
)

# after
assert isinstance(width, int) and isinstance(height, int)
litellm.image_generation(
    model="black_forest_labs/flux-pro-1.1",
    prompt="a cat",
    size=f"{width}x{height}",
)

Defensive patterns

Strategy: validation

Validate before calling

import re

SIZE_RE = re.compile(r"^\d+x\d+$")

def valid_size(size: str) -> bool:
    return bool(SIZE_RE.match(size)) and all(0 < int(p) <= 4096 for p in size.lower().split("x"))

Type guard

def is_valid_bfl_size(size: object) -> bool:
    return (
        isinstance(size, str)
        and "x" in size.lower()
        and len(size.lower().split("x")) == 2
        and all(p.isdigit() for p in size.lower().split("x"))
    )

Try / catch

try:
    litellm.image_generation(model="black_forest_labs/flux-pro-1.1", prompt=p, size=size)
except ValueError as e:
    if "Invalid size format" in str(e):
        size = "1024x1024"  # safe fallback preset
        litellm.image_generation(model="black_forest_labs/flux-pro-1.1", prompt=p, size=size)
    else:
        raise

Prevention

Always build size as f"{int(width)}x{int(height)}" from validated integers.
Prefer preset sizes from the built-in mapping.
Remember strings without 'x' are silently ignored, not validated — check for typos like 'auto'.

When it happens

Trigger: size='1024' (missing height), size='1024x' , size='axb', size='1024x1024x768' (three parts -> ValueError from unpacking), size='1e3x1024' (non-decimal digits). All reach the split branch because they are not in the preset mapping.

Common situations: Building size dynamically ('f'{w}x{h}' with an empty or None height); passing DALL-E shorthand like 'auto', 'large', or 'hd' (silently ignored, not this error — but confusing); locale-formatted numbers ('1,024x1,024').

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: 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 77b7c6c40c)