sgl-project/sglang · error · ValueError

flattened_bucket 'metadata' must be a list.

Error message

flattened_bucket 'metadata' must be a list.

What it means

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.

Source

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

                    "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):
            raise ValueError("flattened_bucket 'metadata' must be a list.")

        converted_metadata: list[FlattenedTensorMetadata] = []
        for meta in metadata:
            converted_metadata.append(
                FlattenedTensorMetadata(
                    name=meta.name,
                    shape=torch.Size(meta.shape),
                    dtype=self._normalize_torch_dtype(meta.dtype),
                    start_idx=int(meta.start_idx),
                    end_idx=int(meta.end_idx),
                    numel=int(meta.numel),
                )
            )

        bucket = FlattenedTensorBucket(
            flattened_tensor=flattened_tensor,
            metadata=converted_metadata,
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Pass metadata as a list of per-tensor metadata objects/namespace-like entries
2. If you received a JSON string, parse it first: json.loads(metadata)

Example fix

// before
{"flattened_tensor": t, "metadata": json.dumps(meta_list)}
// after
{"flattened_tensor": t, "metadata": json.loads(json.dumps(meta_list))}

if isinstance(bucket["metadata"], str):
    import json; bucket["metadata"] = json.loads(bucket["metadata"])

def metadata_is_list(m: Any) -> bool:
    return isinstance(m, list)

When it happens

Trigger: Passing metadata as a JSON string, a dict keyed by tensor name, or a numpy object array with load_format='flattened_bucket'.

Common situations: Round-tripping the bucket through JSON and forgetting json.loads on the metadata field; producer emitting a metadata dict instead of a list.

Related errors

• flattened_bucket payload must be a dict with 'flattened_tens
• flattened_bucket payload missing 'flattened_tensor' or 'meta
• flattened_bucket 'flattened_tensor' must be a torch.Tensor.
• 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/4b06953f2ff75c16. Report an issue: GitHub.