sgl-project/sglang · error · ValueError

flattened_bucket payload missing 'flattened_tensor' or 'meta

Error message

flattened_bucket payload missing 'flattened_tensor' or 'metadata'.

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/post_training/weights_updater.py:775

            return {module_names[0]: named_tensors}

        raise ValueError(
            "Ambiguous tensor payload for multi-module update. "
            "Provide a dict mapping module_name -> module payload, "
            f"requested modules: {module_names}."
        )

    def _materialize_weights_iter(self, module_payload: Any, load_format: str | None):
        if load_format == "flattened_bucket":
            if not isinstance(module_payload, dict):
                raise ValueError(
                    "flattened_bucket payload must be a dict with "
                    "'flattened_tensor' and 'metadata'."
                )
            flattened_tensor = module_payload.get("flattened_tensor")
            metadata = module_payload.get("metadata")
            if flattened_tensor is None or metadata is None:
                raise ValueError(
                    "flattened_bucket payload missing 'flattened_tensor' or 'metadata'."
                )
            return self._reconstruct_from_flattened_bucket(flattened_tensor, metadata)

        if isinstance(module_payload, (list, tuple)):
            return iter(module_payload)

        raise ValueError(
            f"Unsupported module payload type for load_format={load_format}: "
            f"{type(module_payload).__name__}"
        )

    def _reconstruct_from_flattened_bucket(self, flattened_tensor: Any, metadata: Any):
        if not isinstance(flattened_tensor, torch.Tensor):
            raise ValueError(
                "flattened_bucket 'flattened_tensor' must be a torch.Tensor."
            )
        if not isinstance(metadata, list):

View on GitHub (pinned to 0132848349)

Solutions

1. Include both keys with non-None values
2. Check the producing side (trainer/bucket flattener) actually writes both fields

Example fix

// before
{"flattened_tensor": t}
// after
{"flattened_tensor": t, "metadata": [{"name": "w", "offset": 0, "shape": [64], "dtype": "float32"}]}

if not (payload.get("flattened_tensor") is not None and payload.get("metadata") is not None):
    raise ValueError("bucket missing tensor/metadata")

def is_complete_bucket(p: dict) -> bool:
    return p.get("flattened_tensor") is not None and p.get("metadata") is not None

When it happens

Trigger: 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.

Common situations: Hand-building the bucket dict and forgetting one key; metadata serialized as null after round-tripping through JSON.

Related errors

• flattened_bucket payload must be a dict with 'flattened_tens
• flattened_bucket 'flattened_tensor' must be a torch.Tensor.
• flattened_bucket 'metadata' must be a list.
• Unsupported dtype in flattened_bucket metadata: {dtype!r}
• Module(s) requested for update not found in pipeline: {unkno

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