{"record":{"id":"0a6c72d63cdb2574","repo":"vllm-project/vllm","slug":"type-self-name-received-pp-rank-0-handsha","errorCode":null,"errorMessage":"{type(self).__name__} received pp_rank > 0 handshake metadata but does not support PP-disaggregated KV transfer.","messagePattern":"(.+?) received pp_rank > 0 handshake metadata but does not support PP-disaggregated KV transfer\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/base.py","lineNumber":694,"sourceCode":"    ) -> None:\n        \"\"\"\n        Set the KV connector handshake metadata for this connector.\n\n        Args:\n            metadata (KVConnectorHandshakeMetadata): the handshake metadata to set.\n        \"\"\"\n        return None\n\n    def set_xfer_handshake_metadata_pp_aware(\n        self, metadata: dict[tuple[int, int], KVConnectorHandshakeMetadata]\n    ) -> None:\n        \"\"\"\n        Set handshake metadata keyed by (pp_rank, tp_rank).\n        - Default implementation assumes pp_rank is always 0\n        - PP-aware connectors override this to consume all PP producer shards.\n        \"\"\"\n        if any(pp_rank != 0 for pp_rank, _ in metadata):\n            raise ValueError(\n                f\"{type(self).__name__} received pp_rank > 0 handshake metadata \"\n                \"but does not support PP-disaggregated KV transfer.\"\n            )\n        self.set_xfer_handshake_metadata(\n            {tp_rank: meta for (_, tp_rank), meta in metadata.items()}\n        )\n\n    @classmethod\n    def build_prom_metrics(\n        cls,\n        vllm_config: \"VllmConfig\",\n        metric_types: dict[type[\"PromMetric\"], type[\"PromMetricT\"]],\n        labelnames: list[str],\n        per_engine_labelvalues: dict[int, list[object]],\n    ) -> \"KVConnectorPromMetrics | None\":\n        \"\"\"\n        Create a KVConnectorPromMetrics subclass which should register\n        per-connector Prometheus metrics and implement observe() to","sourceCodeStart":676,"sourceCodeEnd":712,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/base.py#L676-L712","documentation":"The default set_xfer_handshake_metadata_pp_aware assumes pipeline-parallel rank 0 only: if the incoming metadata dict contains any (pp_rank, tp_rank) key with pp_rank != 0, the connector clearly does not implement PP-disaggregated KV transfer, and the base class rejects it. Connectors that do support PP-disaggregation must override this method to consume all PP producer shards.","triggerScenarios":"Running with pipeline parallelism (pp > 1) plus a KV connector that only implements set_xfer_handshake_metadata (the tp-only API); the scheduler hands handshake metadata keyed by (pp_rank, tp_rank) including pp_rank > 0, hitting the default implementation.","commonSituations":"Enabling PP on a PD setup with a connector that never added PP support; upgrading a setup to pp>1 with an older/custom connector.","solutions":["Run with pipeline_parallel_size=1 for this connector","Switch to a connector that implements set_xfer_handshake_metadata_pp_aware (PP-disaggregated KV transfer)","For custom connectors, override set_xfer_handshake_metadata_pp_aware to handle pp_rank > 0 shards"],"exampleFix":"# before (base class default only):\n# raise ValueError('received pp_rank > 0 handshake metadata ...')\n\n# after (custom connector adds PP support)\ndef set_xfer_handshake_metadata_pp_aware(self, metadata):\n    for (pp_rank, tp_rank), meta in metadata.items():\n        self._shards[(pp_rank, tp_rank)] = meta","handlingStrategy":"validation","validationCode":"if vllm_config.parallel_config.pipeline_parallel_size > 1:\n    assert type(connector).set_xfer_handshake_metadata_pp_aware is not KVConnectorBase_V1.set_xfer_handshake_metadata_pp_aware, (\n        \"Connector lacks PP-disaggregated KV transfer support\"\n    )","typeGuard":"def supports_pp_kv_transfer(connector) -> bool:\n    return (\n        type(connector).set_xfer_handshake_metadata_pp_aware\n        is not KVConnectorBase_V1.set_xfer_handshake_metadata_pp_aware\n    )","tryCatchPattern":null,"preventionTips":["Check connector PP support before enabling pipeline parallelism","Track which connectors override the pp_aware handshake in your internal docs"],"tags":["kv-transfer","pipeline-parallelism","handshake","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}