sgl-project/sglang · error · ValueError

tar material URI must contain '<tar_path>:<encoded_header>'

Error message

tar material URI must contain '<tar_path>:<encoded_header>'

What it means

After stripping the tar scheme prefix, the remainder must be '<tar_path>:<encoded_header>' — splittable on the last ':'. If there is no ':' at all, rsplit(':',1) yields a single element and the unpack raises, re-raised as this ValueError.

Source

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

        value = ord(character)
        if value not in _BASE64_ALPHABET:
            raise ValueError(
                f"material URI has an invalid base64 character {character!r}"
            )
        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}"

View on GitHub (pinned to 0132848349)

Solutions

1. Append the encoded header: 'tar+offset://{tar_path}:{offset}:{size}' style header per the expected format
2. Regenerate tar member URIs with the library's builder instead of string formatting
3. Validate the URI contains ':' after the scheme prefix before submitting

Example fix

// before
uri = f"tar+offset://{tar_path}"
// after
uri = f"tar+offset://{tar_path}:{offset}:{size}"

rest = uri.split('://', 1)[1] if '://' in uri else uri
assert ':' in rest, 'tar URI missing :<encoded_header> suffix'

def tar_uri_has_header(uri: str) -> bool:
    return uri.startswith(('tar+offset://', 'tar+b64header://')) and ':' in uri.split('://', 1)[1]

When it happens

Trigger: A tar URI like 'tar+offset:///data/x.tar' where the ':<encoded_header>' suffix was omitted, or a header separator replaced by another delimiter.

Common situations: Producer changes that dropped the header suffix, path formats using a different separator, or hand-crafted URIs in tests/tools.

Related errors

• data URI must contain a comma separator
• material URI has an invalid percent escape
• unsupported tar material URI
• tar material URI encoded header is too large
• tar material URI has an invalid encoded header

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