sgl-project/sglang · error · ValueError

material URI has an invalid base64 payload

Error message

material URI has an invalid base64 payload

What it means

A base64 chunk from a data-URI-style material failed strict decoding (b64decode with validate=True and URL-safe altchars '-_'). Any non-alphabet character, bad length, or malformed chunk triggers it.

Source

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

def _material_workdir(batch: Any) -> str:
    registry = batch.extra.setdefault(MINIMAX_H3_TEMP_DIRS_EXTRA_KEY, {})
    material_dirs = registry.get("material")
    if isinstance(material_dirs, list) and material_dirs:
        return str(material_dirs[0])
    return minimax_h3_register_temp_dir(
        batch,
        tempfile.mkdtemp(prefix="minimax_h3_material_"),
        owner="material",
    )


def _decode_base64_chunk(encoded: bytes | bytearray) -> bytes:
    try:
        return base64.b64decode(encoded, altchars=b"-_", validate=True)
    except Exception as exc:
        raise ValueError("material URI has an invalid base64 payload") from exc


def _stream_base64_material(
    batch: Any,
    uri: str,
    *,
    condition_type: str,
    condition_index: int,
) -> str:
    payload_start, media_type = _base64_uri_payload_start(uri)

    output_path, partial_path = _material_output_paths(
        batch,
        condition_type=condition_type,
        condition_index=condition_index,
        media_type=media_type,
    )
    total = 0

View on GitHub (pinned to 0132848349)

Solutions

1. Re-encode with URL-safe alphabet, no padding/newlines: base64.urlsafe_b64encode(data).rstrip(b'=')
2. Strip whitespace/newlines from the payload before embedding
3. If standard base64, translate +/ to -_ before building the URI

Example fix

# before
uri = "data:application/octet-stream;base64," + std_b64  # may contain +/
# after
import base64
safe = base64.urlsafe_b64encode(data).decode().rstrip('=')
uri = "data:application/octet-stream;base64," + safe

import base64
payload = payload_part_of_uri
clean = "".join(payload.split())  # strip whitespace
try:
    base64.b64decode(clean + "=" * (-len(clean) % 4), altchars=b"-_", validate=True)
    ok = True
except Exception:
    ok = False

When it happens

Trigger: Inline base64 material URIs containing whitespace, '+'/'/' instead of '-_'/'_', truncated chunks, or concatenated payload with stray characters, streamed through _stream_base64_material in MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS-sized chunks.

Common situations: Copy-paste corruption, URL-unsafe base64 not translated to the URL-safe alphabet, line-wrapped base64, or truncation from size limits.

Related errors

• material URI has invalid base64 padding
• material URI has data after base64 padding
• data URI must use ;base64 encoding
• material URI base64 payload must be ASCII
• material URI has an invalid base64 character {character!r}

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