What causes "Unsupported object type '{type_name}' in metadata" in vllm-project/vllm?

Make sure all processes sharing the storage run the exact same vLLM build (same serde class)

vllm-project/vllm · error · ValueError

Unsupported object type '{type_name}' in metadata

Error message

Unsupported object type '{type_name}' in metadata

What it means

ShmObjectStorage.deserialize() dispatches on a type-name string stored in the object metadata. It knows how to rebuild tensors, multimodal-kwargs items, and bytes (pickles); any other type_name string reaching the else-branch raises ValueError. This indicates the shared memory holds data serialized by a different/older serde implementation than the one reading it.

Source

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

            obj = []
            start_idx = 0
            for length in len_arr:
                item_bytes = serialized_data[start_idx : start_idx + length]
                obj.append(item_bytes)
                start_idx += length
            obj = self.tensor_decoder.decode(obj)
        elif type_name == self._mm_kwargs_item_cls.__name__:
            obj = []
            start_idx = 0
            for length in len_arr:
                item_bytes = serialized_data[start_idx : start_idx + length]
                obj.append(item_bytes)
                start_idx += length
            obj = self.mm_decoder.decode(obj)
        elif type_name == bytes.__name__:
            obj = pickle.loads(serialized_data)
        else:
            raise ValueError(f"Unsupported object type '{type_name}' in metadata")

        return obj


@dataclass
class ShmObjectStorageHandle:
    max_object_size: int
    n_readers: int
    ring_buffer_handle: tuple[int, str]
    serde_class: type[ObjectSerde]
    reader_lock: LockType | None


class SingleWriterShmObjectStorage:
    """
    A single-writer, multiple-reader object storage system built on top of a
    shared memory ring buffer. Provides key-value storage with automatic memory
    management and cross-process serialization support.

View on GitHub (pinned to c794754062)

Solutions

Make sure all processes sharing the storage run the exact same vLLM build (same serde class)
Remove stale shared-memory segments from the crashed run (unlink the shm file / restart the engine cleanly) before re-attaching
If you added a new serializable type, add a matching decode branch in deserialize() and register it in serialize()

Defensive patterns

Strategy: validation

Validate before calling

# verify build identity before attaching shared memory
import vllm
assert storage.serde.__class__.__name__ == expected_serde_name, (
    "serde mismatch: shm written by a different vLLm build"
)

Try / catch

try:
    obj = storage.get(address, mid)
except ValueError as e:
    if "Unsupported object type" in str(e):
        raise RuntimeError("stale or version-mismatched shm; recreate the segment") from e
    raise

Prevention

Run all processes sharing the storage on the identical vLLm version
Clean up stale /dev/shm segments after crashes before re-attaching
Cover new serde types with round-trip serialize/deserialize tests

When it happens

Trigger: Reading shared memory written by a mismatched vLLM version whose ObjectSerde encodes different type tags; corrupt or zeroed metadata after a crash making the type-name field garbage; or extending the serde with a new type without adding a decoder branch.

Common situations: Upgrading one process (e.g. worker) but not another in a multi-process deployment; stale /dev/shm files left over from a crashed previous run being re-attached; custom subclasses of ObjectSerde that add new serialized types.

Related errors

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