{"record":{"id":"d2ff5661a483c35c","repo":"vllm-project/vllm","slug":"key-key-already-exists-in-the-storage","errorCode":null,"errorMessage":"Key '{key}' already exists in the storage.","messagePattern":"Key '(.+?)' already exists in the storage\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/device_communicators/shm_object_storage.py","lineNumber":579,"sourceCode":"        return address, monotonic_id\n\n    def put(self, key: str, value: Any) -> tuple[int, int]:\n        \"\"\"\n        Store a key-value pair in the object storage.\n        Attempts to free max_object_size bytes using FIFO order\n        when the ring buffer runs out of space during a put() operation.\n\n        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","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/device_communicators/shm_object_storage.py#L561-L597","documentation":"ShmObjectStorage.put() is insert-only: it maintains key_index mapping each key to one (address, monotonic_id) slot and refuses duplicate keys with ValueError. Overwriting would leak the old buffer (its writer_flag entry would never be freed), so the API forces you to use a new key or explicitly remove the old entry first.","triggerScenarios":"Calling put('same_key', obj) twice without an intervening remove/free; retry loops that re-put the same mm_hash key after a partial failure; multiple writers using the same key namespace.","commonSituations":"Retried requests re-inserting the same multimodal hash; component restart that does not rebuild key_index (fresh instance) but shared code assumes insert-once semantics; tests that loop puts with constant keys.","solutions":["Check `key in storage.key_index` (or use the public contains/lookup API) before put() and skip or reuse the existing entry","Use a unique key per insertion (e.g. append the monotonic id or request id)","Free the old entry first via the remove/free path so the slot can be reallocated"],"exampleFix":"# before\nstorage.put(mm_hash, obj)  # may raise: key already exists\n\n# after\nif mm_hash not in storage.key_index:\n    storage.put(mm_hash, obj)\nelse:\n    obj = storage.get(*storage.key_index[mm_hash])","handlingStrategy":"validation","validationCode":"if key in storage.key_index:\n    address, mid = storage.key_index[key]\nelse:\n    storage.put(key, value)","typeGuard":null,"tryCatchPattern":"try:\n    storage.put(key, value)\nexcept ValueError as e:\n    if \"already exists\" not in str(e):\n        raise\n    value = storage.get(*storage.key_index[key])  # reuse existing","preventionTips":["Treat put() as insert-once; gate it with a key_index membership check","Derive keys from content hashes so retries are naturally idempotent","Free the old slot explicitly if overwrite semantics are needed"],"tags":["api-misuse","key-conflict","shared-memory"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}