sgl-project/sglang · error · ValueError

material URI has an invalid base64 payload length

Error message

material URI has an invalid base64 payload length

What it means

The base64 payload length is invalid: either len % 4 == 1 (cannot be valid base64 at all) or padding was present but the total length was not a multiple of 4. The strict decoder refuses such payloads.

Source

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

            for value in _iter_base64_payload_bytes(uri, payload_start):
                encoded_size += 1
                if value == ord("="):
                    saw_padding = True
                    padding += 1
                    if padding > 2:
                        raise ValueError("material URI has invalid base64 padding")
                elif saw_padding:
                    raise ValueError("material URI has data after base64 padding")
                encoded_chunk.append(value)
                if len(encoded_chunk) == MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS:
                    decoded_chunk = _decode_base64_chunk(encoded_chunk)
                    total += len(decoded_chunk)
                    output.write(decoded_chunk)
                    encoded_chunk.clear()
            if encoded_size == 0:
                raise ValueError("material URI base64 payload is empty")
            if encoded_size % 4 == 1 or (padding and encoded_size % 4):
                raise ValueError("material URI has an invalid base64 payload length")
            if encoded_chunk:
                encoded_chunk.extend(b"=" * (-len(encoded_chunk) % 4))
                decoded_chunk = _decode_base64_chunk(encoded_chunk)
                total += len(decoded_chunk)
                output.write(decoded_chunk)
        decoded_size = (encoded_size * 3) // 4 - padding
        if decoded_size <= 0:
            raise ValueError("material URI decoded payload is empty")
        if total != decoded_size:
            raise ValueError(
                f"MiniMax H3 base64 decoded size {total} != expected {decoded_size}"
            )
        partial_path.replace(output_path)
    except Exception:
        partial_path.unlink(missing_ok=True)
        output_path.unlink(missing_ok=True)
        raise
    return str(output_path)

View on GitHub (pinned to 0132848349)

Solutions

1. Re-encode the source bytes with base64.b64encode to get canonical padding
2. If using base64.urlsafe_b64encode output in a URL, keep the '=' chars escaped as %3D
3. Check payload length % 4 == 0 client-side before submission

Example fix

# before
payload = b64.rstrip('=')  # padding no longer consistent
# after
payload = b64  # keep exact b64encode output

assert len(payload) % 4 != 1 and (not payload.endswith('=') or len(payload) % 4 == 0), 'bad b64 length'

except ValueError as e: report malformed base64 URI to caller

When it happens

Trigger: A data/base64 URI whose payload length mod 4 is 1 (e.g. 5 chars), or payload with '=' padding but length not divisible by 4 (e.g. 'AAAAA=').

Common situations: Character loss from copy/paste truncation, URL-unescaping that removed chars, or padding stripped by a URL-safe encoder without re-adding it.

Related errors

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

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