sgl-project/sglang · error · ValueError

material URI base64 payload must be ASCII

Error message

material URI base64 payload must be ASCII

What it means

After percent-decoding and whitespace skipping, every payload character must be a single ASCII character (ord <= 127). This error fires when decoding produced a multi-character string (e.g. an int() yielding a codepoint outside BMP handled via chr producing surrogates is fine, but any character with ord > 127 or a decoded artifact) — i.e. the payload contains non-ASCII bytes, which cannot be valid base64.

Source

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

    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:
                value = int(uri[index + 1 : index + 3], 16)
            except ValueError as exc:
                raise ValueError("material URI has an invalid percent escape") from exc
            index += 3
            character = chr(value)
        else:
            index += 1

        if character.isspace():
            continue
        if len(character) != 1 or ord(character) > 127:
            raise ValueError("material URI base64 payload must be ASCII")
        value = ord(character)
        if value not in _BASE64_ALPHABET:
            raise ValueError(
                f"material URI has an invalid base64 character {character!r}"
            )
        yield value


def _parse_tar_member_uri(uri: str) -> tuple[Path, int, int, str | None]:
    if uri.startswith("tar+offset://"):
        prefix = "tar+offset://"
    elif uri.startswith("tar+b64header://"):
        prefix = "tar+b64header://"
    else:
        raise ValueError("unsupported tar material URI")
    try:
        tar_path, encoded_header = uri[len(prefix) :].rsplit(":", 1)
    except ValueError as exc:

View on GitHub (pinned to 0132848349)

Solutions

1. Base64-encode the raw bytes properly: base64.b64encode(blob).decode('ascii')
2. If the producer percent-encodes, ensure it only encodes ASCII whitespace, not arbitrary bytes
3. Strip/normalize non-ASCII characters from URIs at request ingestion

Example fix

// before
uri = "base64://" + "café"  # non-ASCII text as payload
// after
uri = "base64://" + base64.b64encode("café".encode()).decode('ascii')

try:
    payload.encode('ascii')
except UnicodeEncodeError:
    raise ValueError('material payload is not ASCII/base64')

def payload_is_ascii(payload: str) -> bool:
    try:
        payload.encode('ascii')
        return True
    except UnicodeEncodeError:
        return False

When it happens

Trigger: A base64 payload containing raw UTF-8 multibyte characters, or a percent escape decoding to a codepoint > 127 (e.g. '%C3%A9' decoding to 'é').

Common situations: Passing text that was never base64-encoded, double-encoding mistakes where UTF-8 bytes are percent-encoded into the payload, or copy/paste of base64 with unicode smart quotes.

Related errors

• data URI must use ;base64 encoding
• material URI has an invalid base64 character {character!r}
• tar material URI has an invalid encoded header
• data URI must contain a comma separator
• data URI header is too large

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