{"record":{"id":"2fa83e8c8e3f1bb6","repo":"sgl-project/sglang","slug":"flattened-bucket-payload-missing-flattened-tensor","errorCode":null,"errorMessage":"flattened_bucket payload missing 'flattened_tensor' or 'metadata'.","messagePattern":"flattened_bucket payload missing 'flattened_tensor' or 'metadata'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/post_training/weights_updater.py","lineNumber":775,"sourceCode":"            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        )\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):","sourceCodeStart":757,"sourceCodeEnd":793,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/post_training/weights_updater.py#L757-L793","documentation":"Raised by WeightsUpdater._materialize_weights_iter when the flattened_bucket payload dict exists but is missing 'flattened_tensor' or 'metadata' (either key absent or None). Both are required to reconstruct the module's weights.","triggerScenarios":"Passing a dict like {'flattened_tensor': t} or {'metadata': m} with load_format='flattened_bucket'; also triggers when one of the keys is explicitly None.","commonSituations":"Hand-building the bucket dict and forgetting one key; metadata serialized as null after round-tripping through JSON.","solutions":["Include both keys with non-None values","Check the producing side (trainer/bucket flattener) actually writes both fields"],"exampleFix":"// before\n{\"flattened_tensor\": t}\n// after\n{\"flattened_tensor\": t, \"metadata\": [{\"name\": \"w\", \"offset\": 0, \"shape\": [64], \"dtype\": \"float32\"}]}","handlingStrategy":"validation","validationCode":"if not (payload.get(\"flattened_tensor\") is not None and payload.get(\"metadata\") is not None):\n    raise ValueError(\"bucket missing tensor/metadata\")","typeGuard":"def is_complete_bucket(p: dict) -> bool:\n    return p.get(\"flattened_tensor\") is not None and p.get(\"metadata\") is not None","tryCatchPattern":null,"preventionTips":["Never hand-write bucket dicts; use the flattening utility that produces them","Treat None values as missing, not just absent keys"],"tags":["weights-update","flattened-bucket","missing-key","multimodal"],"backgroundTag":"missing-dict-key","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}