sgl-project/sglang · error · ValueError

Failed to decode base64 image. Expected format: `data:[<medi

Error message

Failed to decode base64 image. Expected format: `data:[<media-type>];base64,<data>`

What it means

save_base64_image_to_path expects a data-URI of the form data:[<media-type>];base64,<data>, and the input did not match the regex data:(.*?)(;base64)?,(.*) at all. This is the generic malformed-input error for inline base64 images (distinct from the missing-marker and empty-payload variants).

Source

Thrown at python/sglang/multimodal_gen/runtime/utils/image_io.py:15

# SPDX-License-Identifier: Apache-2.0
import base64
import os
import re


def save_base64_image_to_path(base64_data: str, target_path: str) -> str:
    b64_format_hint = (
        "Failed to decode base64 image. "
        "Expected format: `data:[<media-type>];base64,<data>`"
    )

    match = re.match(r"data:(.*?)(;base64)?,(.*)", base64_data)
    if not match:
        raise ValueError(b64_format_hint)
    media_type = match.group(1)
    is_base64 = match.group(2)
    if not is_base64:
        raise ValueError(f"{b64_format_hint} (missing ;base64 marker)")
    data = match.group(3)
    if not data:
        raise ValueError(f"{b64_format_hint} (empty data payload)")

    if media_type.startswith("image/"):
        ext = media_type.split("/")[-1].lower()
        if ext == "jpeg":
            ext = "jpg"
    else:
        ext = "jpg"
    target_path = f"{target_path}.{ext}"
    os.makedirs(os.path.dirname(target_path), exist_ok=True)

    try:

View on GitHub (pinned to 0132848349)

Solutions

1. Prefix the payload as data:image/png;base64,<b64data>
2. If you have a URL, use the URL image path instead of the base64 API
3. Strip whitespace/newlines before constructing the data URI

Example fix

// before
save_base64_image_to_path("iVBORw0KGgo...", "/tmp/img")
// after
save_base64_image_to_path("data:image/png;base64,iVBORw0KGgo...", "/tmp/img")

import re
DATA_URI_RE = re.compile(r"data:.*?;base64,.+", re.S)
def is_valid_data_uri(s: str) -> bool:
    return bool(DATA_URI_RE.fullmatch(s.strip()))

def is_data_uri_image(s: str) -> bool:
    return isinstance(s, str) and s.startswith("data:image/") and ";base64," in s

try:
    save_base64_image_to_path(uri, path)
except ValueError as e:
    if "base64" in str(e):
        # reject or fetch from source instead
        ...

When it happens

Trigger: Passing an image string that is not a data URI: a bare base64 blob without the data: prefix, a URL, or arbitrary text — via _maybe_url_image or prepare_warmup_image_path.

Common situations: Frontends sending raw base64 without the data: prefix, copying base64 from files that strip the header, passing an https:// URL where inline data was expected.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• {b64_format_hint} (missing ;base64 marker)
• {b64_format_hint} (empty data payload)
• No base64 image data found
• Cosmos3 action input accepts one image field; use a list or
• data URI must use ;base64 encoding

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/ba4fb0912d9e47ff. Report an issue: GitHub.