sgl-project/sglang · error · ValueError

tar material header requires integer offset_data and size

Error message

tar material header requires integer offset_data and size

What it means

The tar header's offset_data and size fields must be present and convertible to int. Missing keys (KeyError), null/wrong types (TypeError), or non-numeric strings (ValueError) are all re-raised as this single message, since without valid integers the tar member byte range cannot be located.

Source

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

    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,
    )


def _safe_suffix(value: str | None) -> str | None:
    if not value:
        return None
    suffix = Path(urllib.parse.urlsplit(value).path).suffix.lower()
    if suffix and len(suffix) <= 10 and suffix[1:].isalnum():
        return suffix

View on GitHub (pinned to 0132848349)

Solutions

  1. Use integer fields named exactly offset_data and size
  2. Coerce on the producer side: int(member.offset_data), int(member.size) before serializing
  3. Add a producer-side schema check (pydantic/jsonschema) matching the expected keys

Example fix

// before
header = {"schema": "sglang.tar_member_ref/v1", "offset": off, "length": sz}
// after
header = {"schema": "sglang.tar_member_ref/v1", "offset_data": int(off), "size": int(sz)}
Defensive patterns

Strategy: try-catch

Validate before calling

try:
    int(header['offset_data']); int(header['size'])
except (KeyError, TypeError, ValueError):
    raise ValueError('tar header lacks integer offset_data/size')

Type guard

def header_offsets_valid(header) -> bool:
    try:
        return int(header['offset_data']) >= 0 and int(header['size']) >= 0
    except (KeyError, TypeError, ValueError):
        return False

Try / catch

try:
    stream = _stream_tar_member_material(uri)
except ValueError as e:
    if 'offset_data and size' in str(e):
        uri = rebuild_tar_uri(source_tar, member)  # re-emit with correct integer fields
        stream = _stream_tar_member_material(uri)
    else:
        raise

Prevention

When it happens

Trigger: A header JSON like {"schema": "...", "offset": 100} (wrong key name), {"offset_data": "abc", ...}, or {"offset_data": null, ...}.

Common situations: Field renaming between versions (offset vs offset_data), headers written by external tooling with string numerics, or hand-authored headers in tests.

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/7050414d1bdd81f7. Report an issue: GitHub.