{"record":{"id":"4b06953f2ff75c16","repo":"sgl-project/sglang","slug":"flattened-bucket-metadata-must-be-a-list","errorCode":null,"errorMessage":"flattened_bucket 'metadata' must be a list.","messagePattern":"flattened_bucket 'metadata' must be a list\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/post_training/weights_updater.py","lineNumber":794,"sourceCode":"                    \"flattened_bucket payload missing 'flattened_tensor' or 'metadata'.\"\n                )\n            return self._reconstruct_from_flattened_bucket(flattened_tensor, metadata)\n\n        if isinstance(module_payload, (list, tuple)):\n            return iter(module_payload)\n\n        raise ValueError(\n            f\"Unsupported module payload type for load_format={load_format}: \"\n            f\"{type(module_payload).__name__}\"\n        )\n\n    def _reconstruct_from_flattened_bucket(self, flattened_tensor: Any, metadata: Any):\n        if not isinstance(flattened_tensor, torch.Tensor):\n            raise ValueError(\n                \"flattened_bucket 'flattened_tensor' must be a torch.Tensor.\"\n            )\n        if not isinstance(metadata, list):\n            raise ValueError(\"flattened_bucket 'metadata' must be a list.\")\n\n        converted_metadata: list[FlattenedTensorMetadata] = []\n        for meta in metadata:\n            converted_metadata.append(\n                FlattenedTensorMetadata(\n                    name=meta.name,\n                    shape=torch.Size(meta.shape),\n                    dtype=self._normalize_torch_dtype(meta.dtype),\n                    start_idx=int(meta.start_idx),\n                    end_idx=int(meta.end_idx),\n                    numel=int(meta.numel),\n                )\n            )\n\n        bucket = FlattenedTensorBucket(\n            flattened_tensor=flattened_tensor,\n            metadata=converted_metadata,\n        )","sourceCodeStart":776,"sourceCodeEnd":812,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/post_training/weights_updater.py#L776-L812","documentation":"Raised by WeightsUpdater._reconstruct_from_flattened_bucket when the 'metadata' field of a flattened_bucket payload is not a Python list. The code iterates metadata entries to build FlattenedTensorMetadata objects, so any non-list (dict, tuple, JSON string) is rejected.","triggerScenarios":"Passing metadata as a JSON string, a dict keyed by tensor name, or a numpy object array with load_format='flattened_bucket'.","commonSituations":"Round-tripping the bucket through JSON and forgetting json.loads on the metadata field; producer emitting a metadata dict instead of a list.","solutions":["Pass metadata as a list of per-tensor metadata objects/namespace-like entries","If you received a JSON string, parse it first: json.loads(metadata)"],"exampleFix":"// before\n{\"flattened_tensor\": t, \"metadata\": json.dumps(meta_list)}\n// after\n{\"flattened_tensor\": t, \"metadata\": json.loads(json.dumps(meta_list))}","handlingStrategy":"validation","validationCode":"if isinstance(bucket[\"metadata\"], str):\n    import json; bucket[\"metadata\"] = json.loads(bucket[\"metadata\"])","typeGuard":"def metadata_is_list(m: Any) -> bool:\n    return isinstance(m, list)","tryCatchPattern":null,"preventionTips":["Parse JSON string fields immediately after deserialization","Keep metadata as a list through the whole pipeline"],"tags":["weights-update","flattened-bucket","metadata","multimodal"],"backgroundTag":"invalid-payload-format","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}