{"record":{"id":"64d8dad339ba81b4","repo":"vllm-project/vllm","slug":"serialized-object-size-buffer-size-bytes-excee","errorCode":null,"errorMessage":"Serialized object size ({buffer_size} bytes) exceeds max object size ({self.max_object_size} bytes)","messagePattern":"Serialized object size \\((.+?) bytes\\) exceeds max object size \\((.+?) bytes\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/device_communicators/shm_object_storage.py","lineNumber":587,"sourceCode":"        Args:\n            key: String key to identify the object\n            value: Any serializable Python object\n\n        Raises:\n            MemoryError: If there's not enough space in the buffer\n            ValueError: If the serialized object is too large\n            ValueError: If the key already exists in the storage\n        \"\"\"\n        if key in self.key_index:\n            raise ValueError(f\"Key '{key}' already exists in the storage.\")\n\n        object_data, data_bytes, object_metadata, md_bytes = self.ser_de.serialize(\n            value\n        )\n        buffer_size = self.flag_bytes + data_bytes + md_bytes\n        # Sanity checks\n        if buffer_size > self.max_object_size:\n            raise ValueError(\n                f\"Serialized object size ({buffer_size} bytes) exceeds \"\n                f\"max object size ({self.max_object_size} bytes)\"\n            )\n\n        # Allocate new buffer\n        try:\n            address, monotonic_id = self.ring_buffer.allocate_buf(buffer_size)\n        except MemoryError:\n            self.free_unused()\n            # try again after freeing up space\n            address, monotonic_id = self.ring_buffer.allocate_buf(buffer_size)\n\n        # Write data to buffer\n        with self.ring_buffer.access_buf(address) as (data_view, metadata):\n            data_view[: self.flag_bytes] = self.ring_buffer.int2byte(0)\n            self.copy_to_buffer(\n                object_data, data_bytes, object_metadata, md_bytes, data_view\n            )","sourceCodeStart":569,"sourceCodeEnd":605,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/device_communicators/shm_object_storage.py#L569-L605","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"# before\nstorage = ShmObjectStorage(max_object_size=64 * 1024 * 1024, ...)\nstorage.put(k, huge_obj)  # exceeds max object size\n\n# after\nstorage = ShmObjectStorage(max_object_size=512 * 1024 * 1024, ...)\nstorage.put(k, huge_obj)","handlingStrategy":"validation","validationCode":"_, data_bytes, _, md_bytes = serde.serialize(value)\nif storage.flag_bytes + data_bytes + md_bytes > storage.max_object_size:\n    raise SizeError(\"object too large before touching shm\")  # fail early, split payload","typeGuard":null,"tryCatchPattern":"try:\n    storage.put(key, value)\nexcept ValueError as e:\n    if \"exceeds max object size\" in str(e):\n        for i, chunk in enumerate(split(value)):\n            storage.put(f\"{key}:{i}\", chunk)\n    else:\n        raise","preventionTips":["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"],"tags":["configuration","size-limit","serialization"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}