sgl-project/sglang · error · ValueError

material URI has an invalid base64 character {character!r}

Error message

material URI has an invalid base64 character {character!r}

What it means

Every non-whitespace payload character of a base64 material URI must belong to the base64 alphabet (_BASE64_ALPHABET). Characters outside it (after percent-decoding) — e.g. '!', '@', 'é' — raise this error with the offending character shown.

Source

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

        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:
        raise ValueError(
            "tar material URI must contain '<tar_path>:<encoded_header>'"
        ) from exc

View on GitHub (pinned to 0132848349)

Solutions

1. Re-encode the payload with standard base64 (base64.b64encode)
2. If the source is URL-safe base64, convert it: base64.urlsafe_b64decode then b64encode
3. Pre-validate with a regex ^[A-Za-z0-9+/=\s]*$ before invoking the stage

Example fix

// before
uri = "base64://" + urlsafe_b64  # contains '-' or '_'
// after
std_b64 = base64.b64encode(base64.urlsafe_b64decode(urlsafe_b64 + '==')).decode('ascii')
uri = "base64://" + std_b64

import re
if not re.fullmatch(r'[A-Za-z0-9+/=\s]*', payload):
    raise ValueError('payload has non-base64 characters')

def is_standard_base64(payload: str) -> bool:
    import re
    return re.fullmatch(r'[A-Za-z0-9+/=\s]*', payload) is not None

When it happens

Trigger: A payload containing characters outside A-Z, a-z, 0-9, '+', '/', '=', such as a URL-safe '-'/ '_' without urlsafe decoding, raw text, or punctuation.

Common situations: Mixing URL-safe base64 (with '-'/'_') into a standard-alphabet loader, embedding unencoded filenames or metadata in the payload, or corruption during transport.

Related errors

• data URI must use ;base64 encoding
• material URI base64 payload must be ASCII
• 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/9cb701a40540958f. Report an issue: GitHub.