sgl-project/sglang · error · ValueError

Must provide either named_tensors or both flattened_tensor a

Error message

Must provide either named_tensors or both flattened_tensor and metadata

What it means

TensorBucket.__init__ requires either named_tensors or BOTH flattened_tensor and metadata. Passing only one of the pre-flattened pair (or none) is rejected because the bucket cannot reconstruct offsets.

Source

Thrown at python/sglang/srt/weight_sync/tensor_bucket.py:76

                numel = flattened.numel()
                metadata_obj = FlattenedTensorMetadata(
                    name=name,
                    shape=tensor.shape,
                    dtype=tensor.dtype,
                    start_idx=current_idx,
                    end_idx=current_idx + numel,
                    numel=numel,
                )
                self.metadata[i] = metadata_obj
                current_idx += numel

            # Concatenate all flattened tensors
            self.flattened_tensor = torch.cat(flattened_tensors, dim=0)
        else:
            # Initialize from pre-flattened data
            if flattened_tensor is None or metadata is None:
                raise ValueError(
                    "Must provide either named_tensors or both flattened_tensor and metadata"
                )
            self.flattened_tensor = flattened_tensor
            self.metadata = metadata

    def get_flattened_tensor(self) -> torch.Tensor:
        """Get the flattened tensor containing all bucket tensors"""
        return self.flattened_tensor

    def get_metadata(self) -> List[FlattenedTensorMetadata]:
        """Get metadata for all tensors in the bucket"""
        return self.metadata

    def reconstruct_tensors(self) -> List[Tuple[str, torch.Tensor]]:
        """
        Reconstruct original tensors from flattened tensor with optimized performance.
        Uses memory-efficient operations to minimize allocations and copies.
        """

View on GitHub (pinned to 0132848349)

Solutions

1. Pass both flattened_tensor and metadata together
2. Or rebuild from named_tensors instead

Example fix

# before
TensorBucket(flattened_tensor=buf)
# after
TensorBucket(flattened_tensor=buf, metadata=meta)

assert named_tensors is not None or (flattened_tensor is not None and metadata is not None)

When it happens

Trigger: Constructing TensorBucket(flattened_tensor=t) without metadata, or vice versa; deserializing from a partial payload.

Common situations: Custom deserialization code that drops the metadata list; IPC/serialization round-trip losing one field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• f"Unknown feature map: {feature_map}"
• n_q/n_k must be one of {VALID_N}, got n_q={n_q}, n_k={n_k}
• f"Unsupported patch_size type: {type(patch_size)}"
• memory_size must be positive
• consumer_count must be positive

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