sgl-project/sglang · error · ValueError

tar material URI has an invalid encoded header

Error message

tar material URI has an invalid encoded header

What it means

The tar URI's encoded header must base64-decode (with altchars '-_' and validate=True) and parse as UTF-8 JSON. Any failure — bad base64 characters, wrong padding, invalid UTF-8, or JSON syntax errors — surfaces as this ValueError wrapping the original exception.

Source

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

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

View on GitHub (pinned to 0132848349)

Solutions

  1. Build the header as base64.urlsafe_b64encode(json.dumps(header).encode()).decode().rstrip('=')
  2. Round-trip test: parse your generated URI with the same parser before shipping
  3. Avoid inserting whitespace or non-alphabet characters into the header segment

Example fix

// before
encoded = json.dumps(header)  # raw JSON, not base64
// after
import base64, json
encoded = base64.urlsafe_b64encode(json.dumps(header).encode()).decode('ascii').rstrip('=')
uri = f"tar+b64header://{tar_path}:{encoded}"
Defensive patterns

Strategy: try-catch

Validate before calling

import base64, json
def try_decode_header(encoded):
    padded = encoded + '=' * (-len(encoded) % 4)
    return json.loads(base64.b64decode(padded.encode('ascii'), altchars=b'-_', validate=True).decode('utf-8'))

Type guard

def header_decodes(encoded: str) -> bool:
    try:
        try_decode_header(encoded)
        return True
    except Exception:
        return False

Try / catch

try:
    stream = _stream_tar_member_material(uri)
except ValueError as e:
    if 'invalid encoded header' in str(e):
        # regenerate the URI from the source tar and retry once
        uri = rebuild_tar_uri(source_tar, member)
        stream = _stream_tar_member_material(uri)
    else:
        raise

Prevention

When it happens

Trigger: A header segment that isn't valid base64 (e.g. contains spaces or '%'), has incorrect padding, or decodes to text that is not valid JSON.

Common situations: Hand-building headers with json.dumps but forgetting base64, URL-encoding artifacts, or truncation of the URI dropping header tail characters.

Related errors

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