sgl-project/sglang · error · ValueError

unsupported tar material header schema: {header.get('schema'

Error message

unsupported tar material header schema: {header.get('schema')!r}

What it means

The decoded tar header must carry the exact schema marker 'sglang.tar_member_ref/v1' in its 'schema' field. Any other value (or a missing schema key yielding None) raises this error, protecting against incompatible or mis-versioned header formats.

Source

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

    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

Set schema exactly to 'sglang.tar_member_ref/v1' in generated headers
Upgrade producers and consumers together when bumping the schema version
Import the schema constant from the library if exposed, rather than hardcoding the string

Example fix

// before
header = {"schema": "tar_member_ref", "offset_data": o, "size": s}
// after
header = {"schema": "sglang.tar_member_ref/v1", "offset_data": o, "size": s}

Defensive patterns

Strategy: validation

Validate before calling

assert header.get('schema') == 'sglang.tar_member_ref/v1', 'unexpected tar header schema'

Type guard

def header_schema_ok(header) -> bool:
    return isinstance(header, dict) and header.get('schema') == 'sglang.tar_member_ref/v1'

Prevention

Set the schema field explicitly in every producer
Import the schema constant from the library if available

When it happens

Trigger: A header with schema set to a different version string (e.g. 'sglang.tar_member_ref/v2'), a typo, or a header missing the schema field entirely (header.get('schema') is None).

Common situations: Format evolution without a migration path, third-party producers inventing their own schema strings, or copy/paste errors in header templates.

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

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