langchain-ai/langchain · error · ValueError

Must provide one of: url, base64, or file_id

Error message

Must provide one of: url, base64, or file_id

What it means

Raised by the `ImageContentBlock` constructor helper when none of `url`, `base64`, or `file_id` is provided. An image block must reference its payload somewhere; the helper validates this at construction time so the failure happens immediately rather than deep inside a provider call.

Source

Thrown at libs/core/langchain_core/messages/content.py:1035

        index: Index of block in aggregate response.

            Used during streaming.

    Returns:
        A properly formatted `ImageContentBlock`.

    Raises:
        ValueError: If no image source is provided or if `base64` is used without
            `mime_type`.

    !!! note

        The `id` is generated automatically if not provided, using a UUID4 format
        prefixed with `'lc_'` to indicate it is a LangChain-generated ID.
    """
    if not any([url, base64, file_id]):
        msg = "Must provide one of: url, base64, or file_id"
        raise ValueError(msg)

    block = ImageContentBlock(type="image", id=ensure_id(id))

    if url is not None:
        block["url"] = url
    if base64 is not None:
        block["base64"] = base64
    if file_id is not None:
        block["file_id"] = file_id
    if mime_type is not None:
        block["mime_type"] = mime_type
    if index is not None:
        block["index"] = index

    extras = {k: v for k, v in kwargs.items() if v is not None}
    if extras:
        block["extras"] = extras

View on GitHub (pinned to e32fa9a52e)

Solutions

1. Pass at least one of `url=`, `base64=`, or `file_id=` when constructing the block
2. Check the variable holding the source is non-empty before constructing: `if src: ImageContentBlock(url=src)`
3. Default to `base64` with `mime_type` when you have raw bytes

Example fix

# before
block = ImageContentBlock(type="image")  # or helper call with no source args

# after
block = ImageContentBlock(url="https://example.com/cat.png")

def has_image_source_args(url, base64, file_id) -> bool:
    return any([url, base64, file_id])

When it happens

Trigger: Calling the image block constructor with only `mime_type`/`index`/`id`, or with all source arguments as None/empty; conditionally setting a source variable that ends up falsy/unset.

Common situations: Building blocks from optional config fields where the image source was never populated; passing an empty string `url=""` after a template substitution failed; logic bugs where the source key name doesn't match the parameter name.

Related errors

• Unsupported source type. Only 'url' and 'base64' are support
• maxsize must be greater than 0
• Received both `client` and `client_kwargs`. Pass `client_kwa
• Image URL not a data URI; appending as non-standard block.
• mime_type key is required for base64 data.

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/53e7d823faa9fb30. Report an issue: GitHub.