{"record":{"id":"3c64a5fcd0cbb163","repo":"sgl-project/sglang","slug":"flattened-bucket-payload-must-be-a-dict-with-flat","errorCode":null,"errorMessage":"flattened_bucket payload must be a dict with 'flattened_tensor' and 'metadata'.","messagePattern":"flattened_bucket payload must be a dict with 'flattened_tensor' and 'metadata'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/post_training/weights_updater.py","lineNumber":768,"sourceCode":"                raise ValueError(\n                    f\"Missing tensor payload for module(s): {missing}. \"\n                    f\"Provided modules: {list(named_tensors.keys())}\"\n                )\n            return {name: named_tensors[name] for name in module_names}\n\n        if len(module_names) == 1:\n            return {module_names[0]: named_tensors}\n\n        raise ValueError(\n            \"Ambiguous tensor payload for multi-module update. \"\n            \"Provide a dict mapping module_name -> module payload, \"\n            f\"requested modules: {module_names}.\"\n        )\n\n    def _materialize_weights_iter(self, module_payload: Any, load_format: str | None):\n        if load_format == \"flattened_bucket\":\n            if not isinstance(module_payload, dict):\n                raise ValueError(\n                    \"flattened_bucket payload must be a dict with \"\n                    \"'flattened_tensor' and 'metadata'.\"\n                )\n            flattened_tensor = module_payload.get(\"flattened_tensor\")\n            metadata = module_payload.get(\"metadata\")\n            if flattened_tensor is None or metadata is None:\n                raise ValueError(\n                    \"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        )","sourceCodeStart":750,"sourceCodeEnd":786,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/post_training/weights_updater.py#L750-L786","documentation":"Raised by WeightsUpdater._materialize_weights_iter when load_format='flattened_bucket' but the module payload is not a dict. The flattened-bucket format requires a dict containing 'flattened_tensor' and 'metadata' keys.","triggerScenarios":"update_weights_from_tensor(..., load_format=\"flattened_bucket\") with a payload that is a list, tuple, tensor, or other object instead of the expected bucket dict.","commonSituations":"Mixing formats: sending a list of tensors while keeping load_format='flattened_bucket'; producer and consumer disagreeing on the bucket protocol version.","solutions":["Wrap the payload as {'flattened_tensor': tensor, 'metadata': metadata_list}","Or drop load_format so a list/tuple payload is iterated directly"],"exampleFix":"// before\nupdater.update_weights_from_tensor(named_tensors=tensor, load_format=\"flattened_bucket\")\n// after\nupdater.update_weights_from_tensor(named_tensors={\"flattened_tensor\": tensor, \"metadata\": meta}, load_format=\"flattened_bucket\")","handlingStrategy":"validation","validationCode":"if load_format == \"flattened_bucket\":\n    assert isinstance(payload, dict), \"bucket payload must be dict\"","typeGuard":"def is_flattened_bucket(p: Any) -> bool:\n    return isinstance(p, dict) and \"flattened_tensor\" in p and \"metadata\" in p","tryCatchPattern":null,"preventionTips":["Centralize bucket construction in one helper that always emits both keys","Add a round-trip unit test between your flattener and the updater"],"tags":["weights-update","flattened-bucket","validation","multimodal"],"backgroundTag":"invalid-payload-format","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}