vllm-project/vllm · error · ValueError

Key '{key}' already exists in the storage.

Error message

Key '{key}' already exists in the storage.

What it means

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.

Source

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

        return address, monotonic_id

    def put(self, key: str, value: Any) -> tuple[int, int]:
        """
        Store a key-value pair in the object storage.
        Attempts to free max_object_size bytes using FIFO order
        when the ring buffer runs out of space during a put() operation.

        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

View on GitHub (pinned to c794754062)

Solutions

1. Check `key in storage.key_index` (or use the public contains/lookup API) before put() and skip or reuse the existing entry
2. Use a unique key per insertion (e.g. append the monotonic id or request id)
3. Free the old entry first via the remove/free path so the slot can be reallocated

Example fix

# before
storage.put(mm_hash, obj)  # may raise: key already exists

# after
if mm_hash not in storage.key_index:
    storage.put(mm_hash, obj)
else:
    obj = storage.get(*storage.key_index[mm_hash])

if key in storage.key_index:
    address, mid = storage.key_index[key]
else:
    storage.put(key, value)

try:
    storage.put(key, value)
except ValueError as e:
    if "already exists" not in str(e):
        raise
    value = storage.get(*storage.key_index[key])  # reuse existing

When it happens

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

Common situations: 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.

Related errors

• Only readers can dequeue
• Lock must be provided for readers.
• tool response messages require a tool_call_id; use ChatMessa
• request `{request_id}` is already in flight
• engine-core client is closed: {message}

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