run-llama/llama_index · error · ValueError

Invalid data URL format: missing comma separator

Error message

Invalid data URL format: missing comma separator

What it means

Raised while resolving binary data from a `data:` URL when the URL has no comma separating the media-type metadata from the payload. RFC 2397 data URLs have the form `data:[<mediatype>][;base64],<data>`; the parser splits on the first comma, and if none exists the URL cannot contain any data. This is a fail-fast validation inside llama-index-core's binary resolution utility.

Source

Thrown at llama-index-core/llama_index/core/utils.py:678

        return BytesIO(decoded_bytes)

    elif path is not None:
        path = Path(path) if isinstance(path, str) else path
        data = path.read_bytes()
        if as_base64:
            return BytesIO(base64.b64encode(data))
        return BytesIO(data)

    elif url is not None:
        parsed_url = urlparse(url)
        if parsed_url.scheme == "data":
            # Parse data URL: data:[<mediatype>][;base64],<data>
            # The path contains everything after "data:"
            data_part = parsed_url.path

            # Split on the first comma to separate metadata from data
            if "," not in data_part:
                raise ValueError("Invalid data URL format: missing comma separator")

            metadata, url_data = data_part.split(",", 1)
            is_base64_encoded = metadata.endswith(";base64")

            if is_base64_encoded:
                # Data is base64 encoded in the URL
                decoded_data = base64.b64decode(url_data)
                if as_base64:
                    # Return as base64 bytes
                    return BytesIO(base64.b64encode(decoded_data))
                else:
                    # Return decoded binary data
                    return BytesIO(decoded_data)
            else:
                # Data is not base64 encoded in the URL (URL-encoded text)
                if as_base64:
                    # Encode the text data as base64
                    return BytesIO(base64.b64encode(url_data.encode("utf-8")))

View on GitHub (pinned to afd0fef371)

Solutions

1. Fix the URL so it contains a comma and payload: `data:<mediatype>[;base64],<data>`.
2. If building the URL yourself, use `f"data:{mime};base64,{base64.b64encode(data).decode()}"` so the comma is always present.
3. If the payload is genuinely empty, decide whether an empty payload is valid for your flow and handle it before calling the resolver.
4. Log the URL length/schema before passing it in to catch truncation early.

Example fix

# before
url = "data:image/png;base64"  # missing comma + payload
buf = resolve_binary_data(url=url)

# after
import base64
url = f"data:image/png;base64,{base64.b64encode(png_bytes).decode()}"
buf = resolve_binary_data(url=url)

def is_valid_data_url(url: str) -> bool:
    if not url.startswith("data:"):
        return False
    return "," in url[len("data:"):]

try:
    buf = resolve_binary_data(url=url)
except ValueError as e:
    if "data URL" in str(e):
        raise ValueError(f"malformed data URL (len={len(url)}): regenerate it") from e
    raise

When it happens

Trigger: Calling the binary resolver (e.g. `resolve_binary_data` / image readers that accept URLs) with a string like `"data:text/plain"`, `"data:"`, or a truncated data URL where the `,<payload>` part was cut off during copy-paste, templating, or string concatenation.

Common situations: Manually constructing data URLs instead of letting a library encode them; template strings that drop the payload when the base64 variable is empty; LLM/agent pipelines that pass model-generated or user-supplied URLs directly into image/document tools; URL truncation from max-length limits in logs or config files.

Related errors

• No valid source provided to resolve binary data!
• spec_functions must be of type: List[Union[str, Tuple[str, s
• Metadata key must be str!
• Value for metadata {key} must be one of (str, int, float, No
• Max iterations of {max_iterations} reached! Either something

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/27acd7a539552156. Report an issue: GitHub.