{"record":{"id":"b6bab2e17ae18394","repo":"vllm-project/vllm","slug":"not-enough-space-in-the-data-buffer-try-calling-f","errorCode":null,"errorMessage":"Not enough space in the data buffer, try calling free_buf() to free up space","messagePattern":"Not enough space in the data buffer, try calling free_buf\\(\\) to free up space","errorType":"exception","errorClass":"MemoryError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/device_communicators/shm_object_storage.py","lineNumber":216,"sourceCode":"        assert self.is_writer, \"Only the writer can allocate buffers.\"\n        assert size > 0, \"Size must be greater than 0\"\n        assert self.shared_memory.buf is not None, \"Buffer has been closed\"\n        size += self.MD_SIZE  # add metadata size to the buffer size\n        # reset to beginning if the buffer does have enough contiguous space\n        buffer_end_reset = self.data_buffer_end % self.data_buffer_size\n        if buffer_end_reset + size > self.data_buffer_size:\n            buffer_end_reset = (\n                self.data_buffer_end // self.data_buffer_size + 1\n            ) * self.data_buffer_size\n        else:  # no reset needed\n            buffer_end_reset = self.data_buffer_end\n\n        # check if we have enough space in the data buffer\n        # i.e. if the new end (self.data_buffer_end + size)\n        # exceeds the start of the data buffer\n        occupied_size_new = buffer_end_reset + size - self.data_buffer_start\n        if occupied_size_new > self.data_buffer_size:\n            raise MemoryError(\n                \"Not enough space in the data buffer, \"\n                \"try calling free_buf() to free up space\"\n            )\n        self.data_buffer_end = buffer_end_reset\n\n        # first 4 bytes as the monotonic id\n        buf_idx = self.data_buffer_end % self.data_buffer_size\n        self.shared_memory.buf[buf_idx : buf_idx + self.ID_NBYTES] = self.int2byte(\n            self.monotonic_id_end\n        )\n        # next 4 bytes as the size of the data buffer\n        self.shared_memory.buf[buf_idx + self.ID_NBYTES : buf_idx + self.MD_SIZE] = (\n            self.int2byte(size)\n        )\n\n        # record metadata\n        self.metadata[self.monotonic_id_end % self.ID_MAX] = self.data_buffer_end\n        # update buffer and monotonic id indices","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/device_communicators/shm_object_storage.py#L198-L234","documentation":"ShmObjectStorage's ring buffer ran out of contiguous space: after wrapping the write pointer, writing `size` more bytes would overwrite the region starting at data_buffer_start. The check `occupied_size_new > data_buffer_size` fires, meaning live (not yet freed) allocations fill the whole data buffer. The message points you at free_buf()/free_unused(), which releases buffers whose in-use flags have dropped to zero.","triggerScenarios":"Repeated put() calls (e.g. writing encoder-cache / multimodal objects keyed by hash) without matching reader consumption, so writer_flag/id_index entries are never freed; or a single object nearly as large as the whole data_buffer_size; or readers crashing before decrementing the in-use flag.","commonSituations":"Long-running prefill with large multimodal inputs filling shm storage; readers falling behind or being killed so reference counts never reach zero; sizing data_buffer_size too small for the workload's live object set.","solutions":["Call free_unused()/free_buf() (put() itself retries once after free_unused(), so persistent failure means buffers are genuinely still in use)","Ensure every reader calls get() through the API that decrements the in-use flag, and that reader processes stay alive until they release references","Increase the shared data buffer size (storage sizing / max buffer configuration) so live objects fit","If the error is transient (slow readers), add reader-side consumption before more puts"],"exampleFix":"# before\nstorage.put(key, big_obj)  # MemoryError: Not enough space in the data buffer\n\n# after\nstorage.free_unused()  # release buffers whose readers finished\nstorage.put(key, big_obj)","handlingStrategy":"retry","validationCode":"# track live bytes before a burst of puts\nfree = storage.ring_buffer.data_buffer_size - (\n    storage.ring_buffer.data_buffer_end - storage.ring_buffer.data_buffer_start\n)\nif free < incoming_bytes:\n    storage.free_unused()","typeGuard":null,"tryCatchPattern":"try:\n    storage.put(key, value)\nexcept MemoryError:\n    storage.free_unused()  # put() already retries once internally; do more here\n    storage.put(key, value)","preventionTips":["Ensure readers release in-use flags promptly so free_unused() can reclaim buffers","Size data_buffer_size for the worst-case live object set, not the average","Monitor buffer occupancy in long-running multimodal serving"],"tags":["shared-memory","out-of-memory","distributed"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}