{"record":{"id":"c856e045e8487009","repo":"vllm-project/vllm","slug":"request-id-request-id-r-does-not-embed-a-peer-zm-c856e0","errorCode":null,"errorMessage":"request_id {request_id!r} does not embed a peer zmq_address and kv_transfer_params is missing one or more sidecar-fallback keys (need remote_host, remote_handshake_port, remote_notify_port): {e}","messagePattern":"request_id (.+?) does not embed a peer zmq_address and kv_transfer_params is missing one or more sidecar-fallback keys \\(need remote_host, remote_handshake_port, remote_notify_port\\): (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/moriio/moriio_common.py","lineNumber":539,"sourceCode":"        # Try request_id embedded address first, fallback to explicit params.\n        peer_zmq = get_peer_zmq_from_request_id(request_id, is_producer=write_mode)\n        if peer_zmq is not None:\n            remote_host, remote_handshake_port, remote_notify_port = (\n                parse_moriio_zmq_address(peer_zmq)\n            )\n        else:\n            try:\n                remote_host = kv_transfer_params[\"remote_host\"]\n                if not remote_host:\n                    raise ValueError(\n                        f\"request_id {request_id!r} does not embed a peer \"\n                        f\"zmq_address and kv_transfer_params['remote_host'] is \"\n                        f\"empty; cannot route MoRI-IO transfer\"\n                    )\n                remote_handshake_port = int(kv_transfer_params[\"remote_handshake_port\"])\n                remote_notify_port = int(kv_transfer_params[\"remote_notify_port\"])\n            except (KeyError, TypeError, ValueError) as e:\n                raise ValueError(\n                    f\"request_id {request_id!r} does not embed a peer \"\n                    f\"zmq_address and kv_transfer_params is missing one or \"\n                    f\"more sidecar-fallback keys (need remote_host, \"\n                    f\"remote_handshake_port, remote_notify_port): {e}\"\n                ) from e\n\n        # Multi-pod: use multi_pod_hosts list or fallback to single host.\n        _pod_hosts = kv_transfer_params.get(\"remote_hosts\") or [remote_host]\n        if not isinstance(_pod_hosts, list):\n            _pod_hosts = [_pod_hosts]\n        _pod_hosts = [str(h) for h in _pod_hosts]\n        _remote_dp_size_local = int(\n            kv_transfer_params.get(\n                \"remote_dp_size_local\",\n                kv_transfer_params.get(\"remote_dp_size\", 1),\n            )\n        )\n","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/moriio/moriio_common.py#L521-L557","documentation":"Raised in the same peer-resolution fallback path: the request_id carries no embedded zmq_address and kv_transfer_params is missing one or more of remote_host, remote_handshake_port, remote_notify_port (KeyError), has None values (TypeError), or non-numeric ports (ValueError). The chained exception {e} names the failing key or conversion.","triggerScenarios":"Request admission without router-embedded routing plus kv_transfer_params that omits any of the three sidecar keys, sets them to None, or supplies ports as non-integer strings like '55five' or 'tcp://host:5555'.","commonSituations":"Sidecar version drift where new required keys were added; populating params from a JSON that uses different key names; passing the whole zmq address string as remote_host so the int() port conversion is never reached cleanly.","solutions":["Read the chained {e} to identify the exact missing key or bad value","Supply all three keys in kv_transfer_params: remote_host (non-empty str), remote_handshake_port and remote_notify_port as ints or numeric strings","Or enable router-side request_id address embedding so the fallback is unnecessary","Validate the params dict shape at request build time, not at transfer time"],"exampleFix":"// before\nparams = {\"remote_host\": \"10.0.0.5\"}  # ports missing -> KeyError\n\n// after\nparams = {\"remote_host\": \"10.0.0.5\", \"remote_handshake_port\": 5555, \"remote_notify_port\": 5556}","handlingStrategy":"validation","validationCode":"REQUIRED_REMOTE_KEYS = (\"remote_host\", \"remote_handshake_port\", \"remote_notify_port\")\n\ndef validate_sidecar_fallback(params: dict) -> None:\n    for k in REQUIRED_REMOTE_KEYS:\n        if not params.get(k):\n            raise ValueError(f\"kv_transfer_params missing {k}; supply all of {REQUIRED_REMOTE_KEYS}\")\n    int(params[\"remote_handshake_port\"]); int(params[\"remote_notify_port\"])","typeGuard":"def has_sidecar_fallback_keys(params) -> bool:\n    return (\n        isinstance(params, dict)\n        and isinstance(params.get(\"remote_host\"), str)\n        and params[\"remote_host\"].strip() != \"\"\n        and str(params.get(\"remote_handshake_port\", \"\")).isdigit()\n        and str(params.get(\"remote_notify_port\", \"\")).isdigit()\n    )","tryCatchPattern":"try:\n    remote_host, hs, nf = resolve_peer_routing(request_id, kv_transfer_params)\nexcept ValueError as e:\n    # read chained exception to find the exact missing key, then reject request\n    reject_request(request_id, reason=str(e))","preventionTips":["Schema-validate kv_transfer_params at the router/sidecar boundary","Keep a fixture/test that exercises the full fallback key set","Prefer router-embedded zmq_address so this path stays a fallback only"],"tags":["kv-transfer","config","validation","disaggregated-prefill"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}