{"record":{"id":"21bf3f9edf5cb374","repo":"sgl-project/sglang","slug":"tar-material-uri-has-an-invalid-encoded-header","errorCode":null,"errorMessage":"tar material URI has an invalid encoded header","messagePattern":"tar material URI has an invalid encoded header","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py","lineNumber":172,"sourceCode":"    else:\n        raise ValueError(\"unsupported tar material URI\")\n    try:\n        tar_path, encoded_header = uri[len(prefix) :].rsplit(\":\", 1)\n    except ValueError as exc:\n        raise ValueError(\n            \"tar material URI must contain '<tar_path>:<encoded_header>'\"\n        ) from exc\n    if len(encoded_header) > MINIMAX_H3_TAR_HEADER_MAX_ENCODED_CHARS:\n        raise ValueError(\"tar material URI encoded header is too large\")\n    padded = encoded_header + \"=\" * (-len(encoded_header) % 4)\n    try:\n        header = json.loads(\n            base64.b64decode(\n                padded.encode(\"ascii\"), altchars=b\"-_\", validate=True\n            ).decode(\"utf-8\")\n        )\n    except Exception as exc:\n        raise ValueError(\"tar material URI has an invalid encoded header\") from exc\n    if not isinstance(header, dict):\n        raise ValueError(\"tar material URI header must be a JSON object\")\n    if header.get(\"schema\") != \"sglang.tar_member_ref/v1\":\n        raise ValueError(\n            f\"unsupported tar material header schema: {header.get('schema')!r}\"\n        )\n    try:\n        offset = int(header[\"offset_data\"])\n        size = int(header[\"size\"])\n    except (KeyError, TypeError, ValueError) as exc:\n        raise ValueError(\n            \"tar material header requires integer offset_data and size\"\n        ) from exc\n    if offset < 0 or size < 0:\n        raise ValueError(\"tar material offset_data and size must be non-negative\")\n    return (\n        Path(tar_path).expanduser(),\n        offset,","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py#L154-L190","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-building headers with json.dumps but forgetting base64, URL-encoding artifacts, or truncation of the URI dropping header tail characters.","solutions":["Build the header as base64.urlsafe_b64encode(json.dumps(header).encode()).decode().rstrip('=')","Round-trip test: parse your generated URI with the same parser before shipping","Avoid inserting whitespace or non-alphabet characters into the header segment"],"exampleFix":"// before\nencoded = json.dumps(header)  # raw JSON, not base64\n// after\nimport base64, json\nencoded = base64.urlsafe_b64encode(json.dumps(header).encode()).decode('ascii').rstrip('=')\nuri = f\"tar+b64header://{tar_path}:{encoded}\"","handlingStrategy":"try-catch","validationCode":"import base64, json\ndef try_decode_header(encoded):\n    padded = encoded + '=' * (-len(encoded) % 4)\n    return json.loads(base64.b64decode(padded.encode('ascii'), altchars=b'-_', validate=True).decode('utf-8'))","typeGuard":"def header_decodes(encoded: str) -> bool:\n    try:\n        try_decode_header(encoded)\n        return True\n    except Exception:\n        return False","tryCatchPattern":"try:\n    stream = _stream_tar_member_material(uri)\nexcept ValueError as e:\n    if 'invalid encoded header' in str(e):\n        # regenerate the URI from the source tar and retry once\n        uri = rebuild_tar_uri(source_tar, member)\n        stream = _stream_tar_member_material(uri)\n    else:\n        raise","preventionTips":["Build headers with base64.urlsafe_b64encode(json.dumps(...))","Round-trip test generated URIs in producer tests"],"tags":["minimax-h3","tar-uri","base64","json","material-io"],"backgroundTag":"invalid-base64-payload","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}