sgl-project/sglang · error · ValueError

tar material URI header must be a JSON object

Error message

tar material URI header must be a JSON object

What it means

After decoding, the tar material header must be a JSON object (dict). Decoding to a list, string, number, or null raises this error, since the header is expected to carry keyed fields like schema, offset_data, and size.

Source

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

    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"])
    except (KeyError, TypeError, ValueError) as exc:
        raise ValueError(
            "tar material header requires integer offset_data and size"
        ) from exc
    if offset < 0 or size < 0:
        raise ValueError("tar material offset_data and size must be non-negative")
    return (
        Path(tar_path).expanduser(),
        offset,
        size,
        str(header.get("member") or "") or None,

View on GitHub (pinned to 0132848349)

Solutions

1. Encode a dict: {"schema": "sglang.tar_member_ref/v1", "offset_data": ..., "size": ...}
2. If migrating formats, version the schema field and convert on read
3. Add a producer-side unit test that the emitted header round-trips to a dict

Example fix

// before
header = [offset, size]  # array
// after
header = {"schema": "sglang.tar_member_ref/v1", "offset_data": offset, "size": size}

header = try_decode_header(encoded)
assert isinstance(header, dict), 'tar header must be a JSON object'

def header_is_object(header) -> bool:
    return isinstance(header, dict)

When it happens

Trigger: A header encoding a JSON array or scalar, e.g. base64 of '[1,2,3]' or '"schema=v1"'.

Common situations: Producers that encode a compact positional list instead of a dict, or version drift where an older header format was an array.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• tar material URI has an invalid encoded header
• unsupported tar material URI
• tar material URI must contain '<tar_path>:<encoded_header>'
• tar material URI encoded header is too large
• unsupported tar material header schema: {header.get('schema'

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