BerriAI/litellm · error · ValueError

Empty image_url string is not valid.

Error message

Empty image_url string is not valid.

What it means

An image_url given as a plain string must be non-empty after stripping whitespace - an empty or whitespace-only string has no tokens to count and almost always signals a bug in the caller's data assembly.

Source

Thrown at litellm/litellm_core_utils/token_counter.py:600

    Raises:
        ValueError: If image_url is invalid type or detail value is invalid
    """
    if isinstance(image_url, dict):
        detail: Final = image_url.get("detail", "auto")
        if detail not in ["low", "high", "auto"]:
            raise ValueError(f"Invalid detail value: {detail}. Expected 'low', 'high', or 'auto'.")
        url: Final = image_url.get("url")
        if not url:
            raise ValueError("Missing required key 'url' in image_url dict.")
        return calculate_img_tokens(
            data=url,
            mode=detail,
            use_default_image_token_count=use_default_image_token_count,
        )
    elif isinstance(image_url, str):
        if not image_url.strip():
            raise ValueError("Empty image_url string is not valid.")
        return calculate_img_tokens(
            data=image_url,
            mode="auto",
            use_default_image_token_count=use_default_image_token_count,
        )
    else:
        raise ValueError(f"Invalid image_url type: {type(image_url).__name__}. Expected str or dict with 'url' field.")


def _validate_anthropic_content(content: Mapping[str, Any]) -> type:
    """
    Validate and determine which Anthropic TypedDict applies.

    Returns the corresponding TypedDict class if recognized, otherwise raises.
    """
    content_type: Final = content.get("type")
    if not content_type:
        raise ValueError("Anthropic content missing required field: 'type'")

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Skip image blocks whose url is blank instead of passing them on.
2. Fail loudly at your input boundary when an image attachment is required but empty.

Example fix

# before
blocks = [{"type": "image_url", "image_url": url} for url in urls]  # url may be ""

# after
blocks = [{"type": "image_url", "image_url": url} for url in urls if url and url.strip()]

urls = [u for u in urls if isinstance(u, str) and u.strip()]  # drop blanks before building blocks

def is_nonempty_image_url(value) -> bool:
    return isinstance(value, str) and bool(value.strip())

When it happens

Trigger: image_url set to an empty or whitespace-only string - typically a blank value from a template, an unset variable interpolated via f-string, or a user form submitted without an image.

Common situations: Users submitting forms without attaching an image; empty template placeholders; base64-encoding of an empty file producing an empty string upstream.

Related errors

• Invalid detail value: {detail}. Expected 'low', 'high', or '
• Missing required key 'url' in image_url dict.
• Invalid image_url type: {type(image_url).__name__}. Expected
• Image url not in expected format. Example Expected input - "
• text and messages cannot both be set

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