vllm-project/vllm · error · ValueError

Serialized object size ({buffer_size} bytes) exceeds max obj

Error message

Serialized object size ({buffer_size} bytes) exceeds max object size ({self.max_object_size} bytes)

What it means

The serialized form of the object (flag bytes + data bytes + metadata bytes) exceeds max_object_size, the per-object cap of ShmObjectStorage. Unlike a full ring buffer (MemoryError), this is a hard per-object limit: even freeing space cannot fit an object larger than the maximum slot size.

Source

Thrown at vllm/distributed/device_communicators/shm_object_storage.py:587

        Args:
            key: String key to identify the object
            value: Any serializable Python object

        Raises:
            MemoryError: If there's not enough space in the buffer
            ValueError: If the serialized object is too large
            ValueError: If the key already exists in the storage
        """
        if key in self.key_index:
            raise ValueError(f"Key '{key}' already exists in the storage.")

        object_data, data_bytes, object_metadata, md_bytes = self.ser_de.serialize(
            value
        )
        buffer_size = self.flag_bytes + data_bytes + md_bytes
        # Sanity checks
        if buffer_size > self.max_object_size:
            raise ValueError(
                f"Serialized object size ({buffer_size} bytes) exceeds "
                f"max object size ({self.max_object_size} bytes)"
            )

        # Allocate new buffer
        try:
            address, monotonic_id = self.ring_buffer.allocate_buf(buffer_size)
        except MemoryError:
            self.free_unused()
            # try again after freeing up space
            address, monotonic_id = self.ring_buffer.allocate_buf(buffer_size)

        # Write data to buffer
        with self.ring_buffer.access_buf(address) as (data_view, metadata):
            data_view[: self.flag_bytes] = self.ring_buffer.int2byte(0)
            self.copy_to_buffer(
                object_data, data_bytes, object_metadata, md_bytes, data_view
            )

View on GitHub (pinned to c794754062)

Solutions

Increase max_object_size (and the underlying shm region size) to comfortably exceed your largest serialized object
Split the object: store per-chunk or per-image entries under separate keys instead of one giant payload
Shrink the payload before put() (e.g. move large tensors through the tensor path rather than pickling them as bytes)

Example fix

# before
storage = ShmObjectStorage(max_object_size=64 * 1024 * 1024, ...)
storage.put(k, huge_obj)  # exceeds max object size

# after
storage = ShmObjectStorage(max_object_size=512 * 1024 * 1024, ...)
storage.put(k, huge_obj)

Defensive patterns

Strategy: validation

Validate before calling

_, data_bytes, _, md_bytes = serde.serialize(value)
if storage.flag_bytes + data_bytes + md_bytes > storage.max_object_size:
    raise SizeError("object too large before touching shm")  # fail early, split payload

Try / catch

try:
    storage.put(key, value)
except ValueError as e:
    if "exceeds max object size" in str(e):
        for i, chunk in enumerate(split(value)):
            storage.put(f"{key}:{i}", chunk)
    else:
        raise

Prevention

Budget max_object_size against your largest multimodal payload plus pickle overhead
Split oversized payloads into per-item keys
Add a startup smoke test that puts the worst-case object size

When it happens

Trigger: Storing a very large multimodal embedding/image payload whose serialized size (including pickle metadata overhead) exceeds the configured max_object_size; putting an object that accidentally holds an unserializable-by-size payload like a full video tensor.

Common situations: Multimodal workloads with large images/videos/high-res inputs on encoder-cache transfer paths; max_object_size left at a default tuned for small tensors; embeddings batched into one object after a refactor.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/64d8dad339ba81b4. Report an issue: GitHub.