What causes "unsupported tar material URI" in sgl-project/sglang?

Use exactly 'tar+offset:// : ' or 'tar+b64header:// : '

sgl-project/sglang · error · ValueError

unsupported tar material URI

Error message

unsupported tar material URI

What it means

_parse_tar_member_uri only accepts URIs with the schemes 'tar+offset://' or 'tar+b64header://'. Any other scheme reaching this parser raises 'unsupported tar material URI', indicating the routing layer misclassified the URI or the scheme is misspelled.

Source

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

        if character.isspace():
            continue
        if len(character) != 1 or ord(character) > 127:
            raise ValueError("material URI base64 payload must be ASCII")
        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):

View on GitHub (pinned to 0132848349)

Solutions

Use exactly 'tar+offset://<tar_path>:<header>' or 'tar+b64header://<tar_path>:<header>'
Fix the dispatcher so non-tar schemes route to the base64 streamer instead
Centralize scheme constants instead of string literals on both producer and consumer sides

Example fix

// before
uri = f"tar://{tar_path}:{header}"
// after
uri = f"tar+b64header://{tar_path}:{encoded_header}"

Defensive patterns

Strategy: type-guard

Validate before calling

if not (uri.startswith('tar+offset://') or uri.startswith('tar+b64header://')):
    raise ValueError('not a supported tar material URI')

Type guard

def is_supported_tar_uri(uri: str) -> bool:
    return uri.startswith('tar+offset://') or uri.startswith('tar+b64header://')

Prevention

Use shared scheme constants from producer and consumer
Route unknown schemes to a generic error, not the tar parser

When it happens

Trigger: Calling the tar-member streaming path with a URI like 'tar://...', 'tar+json://...', or one missing the scheme entirely.

Common situations: Adding a new tar URI scheme without updating the parser, typos in scheme strings built by a producer, or dispatch logic that defaults unknown schemes to the tar path.

Related errors

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