sgl-project/sglang · error · ValueError

flattened_bucket payload must be a dict with 'flattened_tens

Error message

flattened_bucket payload must be a dict with 'flattened_tensor' and 'metadata'.

What it means

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.

Source

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

                raise ValueError(
                    f"Missing tensor payload for module(s): {missing}. "
                    f"Provided modules: {list(named_tensors.keys())}"
                )
            return {name: named_tensors[name] for name in module_names}

        if len(module_names) == 1:
            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__}"
        )

View on GitHub (pinned to 0132848349)

Solutions

Wrap the payload as {'flattened_tensor': tensor, 'metadata': metadata_list}
Or drop load_format so a list/tuple payload is iterated directly

Example fix

// before
updater.update_weights_from_tensor(named_tensors=tensor, load_format="flattened_bucket")
// after
updater.update_weights_from_tensor(named_tensors={"flattened_tensor": tensor, "metadata": meta}, load_format="flattened_bucket")

Defensive patterns

Strategy: validation

Validate before calling

if load_format == "flattened_bucket":
    assert isinstance(payload, dict), "bucket payload must be dict"

Type guard

def is_flattened_bucket(p: Any) -> bool:
    return isinstance(p, dict) and "flattened_tensor" in p and "metadata" in p

Prevention

Centralize bucket construction in one helper that always emits both keys
Add a round-trip unit test between your flattener and the updater

When it happens

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

Common situations: Mixing formats: sending a list of tensors while keeping load_format='flattened_bucket'; producer and consumer disagreeing on the bucket protocol version.

Related errors

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