sgl-project/sglang · error · ValueError

tar material URI encoded header is too large

Error message

tar material URI encoded header is too large

What it means

The base64-encoded JSON header segment of a tar material URI must not exceed MINIMAX_H3_TAR_HEADER_MAX_ENCODED_CHARS. This bounds memory/parse cost and rejects corrupted URIs where the header and path got swapped or the header is garbage.

Source

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

            )
        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
    if len(encoded_header) > MINIMAX_H3_TAR_HEADER_MAX_ENCODED_CHARS:
        raise ValueError("tar material URI encoded header is too large")
    padded = encoded_header + "=" * (-len(encoded_header) % 4)
    try:
        header = json.loads(
            base64.b64decode(
                padded.encode("ascii"), altchars=b"-_", validate=True
            ).decode("utf-8")
        )
    except Exception as exc:
        raise ValueError("tar material URI has an invalid encoded header") from exc
    if not isinstance(header, dict):
        raise ValueError("tar material URI header must be a JSON object")
    if header.get("schema") != "sglang.tar_member_ref/v1":
        raise ValueError(
            f"unsupported tar material header schema: {header.get('schema')!r}"
        )
    try:
        offset = int(header["offset_data"])
        size = int(header["size"])

View on GitHub (pinned to 0132848349)

Solutions

1. Keep the JSON header minimal (schema, offset_data, size) so the encoded form stays small
2. If the tar path may contain ':', use rsplit semantics consistently on the producer side or forbid ':' in paths
3. Regenerate the URI from a known-good tar member reference

Example fix

// before
header = {"schema": "...", "offset_data": 0, "size": n, "blob": giant_payload}
// after
header = {"schema": "sglang.tar_member_ref/v1", "offset_data": offset, "size": size}

encoded = uri.split('://', 1)[1].rsplit(':', 1)[1]
assert len(encoded) <= MINIMAX_H3_TAR_HEADER_MAX_ENCODED_CHARS

def tar_header_size_ok(uri: str, cap: int) -> bool:
    try:
        encoded = uri.split('://', 1)[1].rsplit(':', 1)[1]
    except (IndexError, ValueError):
        return False
    return len(encoded) <= cap

When it happens

Trigger: A tar+b64header:// URI whose encoded header segment exceeds the cap — usually because rsplit(':',1) grabbed the wrong segment (path containing ':' pushing a huge segment into the header) or a corrupted URI.

Common situations: Tar paths containing ':' making the split ambiguous, corrupt URIs after transport truncation, or headers accidentally embedding large payloads.

Related errors

• data URI header is too large
• base64 URI header is too large
• unsupported tar material URI
• tar material URI must contain '<tar_path>:<encoded_header>'
• tar material URI has an invalid encoded header

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