sgl-project/sglang · error · ValueError

base64 URI header is too large

Error message

base64 URI header is too large

What it means

For 'base64://' scheme URIs, an optional media-type segment may precede a ','; that segment must stay within MINIMAX_H3_BASE64_HEADER_MAX_CHARS. The error fires when the comma-delimited header portion of a base64:// URI exceeds the cap.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py:110

def _base64_uri_payload_start(uri: str) -> tuple[int, str | None]:
    media_type = None
    if uri.startswith("data:"):
        separator = uri.find(",")
        if separator < 0:
            raise ValueError("data URI must contain a comma separator")
        if separator > MINIMAX_H3_BASE64_HEADER_MAX_CHARS:
            raise ValueError("data URI header is too large")
        header = uri[:separator]
        if ";base64" not in header:
            raise ValueError("data URI must use ;base64 encoding")
        media_type = header[5:].split(";", 1)[0].lower() or None
        payload_start = separator + 1
    elif uri.startswith("base64://"):
        payload_start = len("base64://")
        separator = uri.find(",", payload_start)
        if separator >= 0:
            if separator - payload_start > MINIMAX_H3_BASE64_HEADER_MAX_CHARS:
                raise ValueError("base64 URI header is too large")
            header = uri[payload_start:separator]
            media_type = header.split(";", 1)[0].lower() or None
            payload_start = separator + 1
    else:  # pragma: no cover - guarded by the caller
        raise ValueError("not a base64 material URI")
    return payload_start, media_type


def _iter_base64_payload_bytes(uri: str, payload_start: int):
    """Yield validated, unquoted base64 bytes without copying the payload."""

    index = payload_start
    while index < len(uri):
        character = uri[index]
        if character == "%":
            if index + 2 >= len(uri):
                raise ValueError("material URI has an invalid percent escape")
            try:

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure the optional header segment is short and followed by ',' before the payload
2. If no media type is needed, emit 'base64://<payload>' with no comma at all
3. Validate comma position (if present, must be within the header cap) at ingestion

Example fix

// before
uri = "base64://image/png" + payload  # missing comma
// after
uri = "base64://image/png," + payload  # or simply "base64://" + payload

if uri.startswith('base64://'):
    sep = uri.find(',', len('base64://'))
    if sep >= 0 and sep - len('base64://') > MINIMAX_H3_BASE64_HEADER_MAX_CHARS:
        raise ValueError('base64 URI header too large')

def base64_uri_header_ok(uri: str, cap: int) -> bool:
    sep = uri.find(',', len('base64://'))
    return sep < 0 or sep - len('base64://') <= cap

When it happens

Trigger: A base64:// URI whose text before the first ',' is longer than the header cap — typically because the comma separator was lost and the base64 payload itself is being counted as header.

Common situations: Malformed base64:// URIs where the payload was appended without the ',' separator, or a media-type segment stuffed with junk.

Related errors

• data URI header is too large
• tar material URI encoded header is too large
• data URI must contain a comma separator
• data URI must use ;base64 encoding
• material URI has an invalid percent escape

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