Your current environment

============================== System Info

OS : Ubuntu 22.04.4 LTS (x86_64) GCC version : (Ubuntu 12.3.0-1ubuntu1~22.04.3) 12.3.0 Clang version : Could not collect CMake version : version 3.22.1 Libc version : glibc-2.35

============================== PyTorch Info

PyTorch version : 2.11.0+cu129 Is debug build : False CUDA used to build PyTorch : 12.9 ROCM used to build PyTorch : N/A XPU used to build PyTorch : N/A

============================== Python Environment

Python version : 3.12.11 (main, Jul 23 2025, 00:34:44) [Clang 20.1.4 ] (64-bit runtime) Python platform : Linux-5.15.0-176-generic-x86_64-with-glibc2.35

============================== CUDA / GPU Info

Is CUDA available : True CUDA runtime version : Could not collect CUDA_MODULE_LOADING set to : GPU models and configuration : GPU 0: NVIDIA A100 80GB PCIe GPU 1: NVIDIA A100 80GB PCIe GPU 2: NVIDIA A100 80GB PCIe GPU 3: NVIDIA A100 80GB PCIe

Nvidia driver version : 560.35.03 cuDNN version : Could not collect HIP runtime version : N/A MIOpen runtime version : N/A Is XNNPACK available : True

============================== CPU Info

Architecture: x86_64 CPU op-mode(s): 32-bit, 64-bit Address sizes: 52 bits physical, 57 bits virtual Byte Order: Little Endian CPU(s): 128 On-line CPU(s) list: 0-127 Vendor ID: GenuineIntel Model name: Intel(R) Xeon(R) Gold 6430 CPU family: 6 Model: 143 Thread(s) per core: 2 Core(s) per socket: 32 Socket(s): 2 Stepping: 8 CPU max MHz: 3400.0000 CPU min MHz: 800.0000 BogoMIPS: 4200.00 Flags: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall nx pdpe1gb rdtscp lm constant_tsc art arch_perfmon pebs bts rep_good nopl xtopology nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq dtes64 monitor ds_cpl vmx smx est tm2 ssse3 sdbg fma cx16 xtpr pdcm pcid dca sse4_1 sse4_2 x2apic movbe popcnt tsc_deadline_timer aes xsave avx f16c rdrand lahf_lm abm 3dnowprefetch cpuid_fault epb cat_l3 cat_l2 cdp_l3 invpcid_single intel_ppin cdp_l2 ssbd mba ibrs ibpb stibp ibrs_enhanced tpr_shadow vnmi flexpriority ept vpid ept_ad fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid cqm rdt_a avx512f avx512dq rdseed adx smap avx512ifma clflushopt clwb intel_pt avx512cd sha_ni avx512bw avx512vl xsaveopt xsavec xgetbv1 xsaves cqm_llc cqm_occup_llc cqm_mbm_total cqm_mbm_local split_lock_detect avx_vnni avx512_bf16 wbnoinvd dtherm ida arat pln pts hwp hwp_act_window hwp_epp hwp_pkg_req avx512vbmi umip pku ospke waitpkg avx512_vbmi2 gfni vaes vpclmulqdq avx512_vnni avx512_bitalg tme avx512_vpopcntdq la57 rdpid bus_lock_detect cldemote movdiri movdir64b enqcmd fsrm md_clear serialize tsxldtrk pconfig arch_lbr amx_bf16 avx512_fp16 amx_tile amx_int8 flush_l1d arch_capabilities ibpb_exit_to_user Virtualization: VT-x L1d cache: 3 MiB (64 instances) L1i cache: 2 MiB (64 instances) L2 cache: 128 MiB (64 instances) L3 cache: 120 MiB (2 instances) NUMA node(s): 2 NUMA node0 CPU(s): 0-31,64-95 NUMA node1 CPU(s): 32-63,96-127 Vulnerability Gather data sampling: Not affected Vulnerability Indirect target selection: Not affected Vulnerability Itlb multihit: Not affected Vulnerability L1tf: Not affected Vulnerability Mds: Not affected Vulnerability Meltdown: Not affected Vulnerability Mmio stale data: Not affected Vulnerability Reg file data sampling: Not affected Vulnerability Retbleed: Not affected Vulnerability Spec rstack overflow: Not affected Vulnerability Spec store bypass: Mitigation; Speculative Store Bypass disabled via prctl and seccomp Vulnerability Spectre v1: Mitigation; usercopy/swapgs barriers and __user pointer sanitization Vulnerability Spectre v2: Mitigation; Enhanced / Automatic IBRS; IBPB conditional; PBRSB-eIBRS SW sequence; BHI BHI_DIS_S Vulnerability Srbds: Not affected Vulnerability Tsa: Not affected Vulnerability Tsx async abort: Not affected Vulnerability Vmscape: Mitigation; IBPB before exit to userspace

============================== Versions of relevant libraries

[pip3] flashinfer-python==0.6.8.post1 [pip3] numpy==2.3.5 [pip3] nvidia-cublas-cu12==12.9.1.4 [pip3] nvidia-cuda-cupti-cu12==12.9.79 [pip3] nvidia-cuda-nvrtc-cu12==12.9.86 [pip3] nvidia-cuda-runtime-cu12==12.9.79 [pip3] nvidia-cudnn-cu12==9.17.1.4 [pip3] nvidia-cudnn-frontend==1.18.0 [pip3] nvidia-cufft-cu12==11.4.1.4 [pip3] nvidia-cufile-cu12==1.14.1.1 [pip3] nvidia-curand-cu12==10.3.10.19 [pip3] nvidia-cusolver-cu12==11.7.5.82 [pip3] nvidia-cusparse-cu12==12.5.10.65 [pip3] nvidia-cusparselt-cu12==0.7.1 [pip3] nvidia-cutlass-dsl==4.4.2 [pip3] nvidia-cutlass-dsl-libs-base==4.4.2 [pip3] nvidia-ml-py==13.595.45 [pip3] nvidia-nccl-cu12==2.28.9 [pip3] nvidia-nvjitlink-cu12==12.9.86 [pip3] nvidia-nvshmem-cu12==3.4.5 [pip3] nvidia-nvtx-cu12==12.9.79 [pip3] pyzmq==27.1.0 [pip3] torch==2.11.0+cu129 [pip3] torch_c_dlpack_ext==0.1.5 [pip3] torchaudio==2.11.0 [pip3] torchvision==0.26.0+cu129 [pip3] transformers==5.7.0 [pip3] triton==3.6.0 [conda] Could not collect

============================== vLLM Info

ROCM Version : 6.2.41133-dd7f95766 vLLM Version : 0.20.0 vLLM Build Flags: CUDA Archs: Not Set; ROCm: Disabled; XPU: Disabled GPU Topology: GPU0 GPU1 GPU2 GPU3 CPU Affinity NUMA Affinity GPU NUMA ID GPU0 X NV12 PXB PXB 0-31,64-95 0 N/A GPU1 NV12 X PXB PXB 0-31,64-95 0 N/A GPU2 PXB PXB X NV12 0-31,64-95 0 N/A GPU3 PXB PXB NV12 X 0-31,64-95 0 N/A

Legend:

X = Self SYS = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI) NODE = Connection traversing PCIe as well as the interconnect between PCIe Host Bridges within a NUMA node PHB = Connection traversing PCIe as well as a PCIe Host Bridge (typically the CPU) PXB = Connection traversing multiple PCIe bridges (without traversing the PCIe Host Bridge) PIX = Connection traversing at most a single PCIe bridge NV# = Connection traversing a bonded set of # NVLinks

🐛 Describe the bug

Summary

When using MooncakeConnector with disaggregated prefill/decode on a multi-homed machine, vLLM/Mooncake may auto-select the wrong local IP address if VLLM_HOST_IP is not set.

This causes Mooncake KV transfer to fail even though the HTTP API endpoints are reachable and correctly configured.

In my case:

• Prefill HTTP API: http://10.208.130.107:8010
• Decode HTTP API: http://10.208.130.185:8020

However, on the decode host, Mooncake auto-selected 192.168.30.10 instead of 10.208.130.185, and the KV transfer later failed with:

Mooncake transfer engine returned -1

Setting:

export VLLM_HOST_IP=10.208.130.185

fixed the problem immediately.

Reproduction

Decode host

hostname -I output:

10.208.130.185 192.168.5.13 192.168.30.10 172.17.0.1 172.17.46.0

Without setting VLLM_HOST_IP, the decode side started with logs like:

Transfer Engine parseHostNameWithPort. server_name: 192.168.30.10 port: 12001
Transfer Engine RPC using P2P handshake, listening on 192.168.30.10:15301

But the intended reachable IP between prefill/decode nodes was:

10.208.130.185

This later caused KV transfer failure.

After setting:

export VLLM_HOST_IP=10.208.130.185

the issue disappeared.

Why this is confusing

The proxy is configured with the correct HTTP endpoints:

python mooncake_connector_proxy.py \
  --prefill http://10.208.130.107:8010 \
  --decode http://10.208.130.185:8020

So from a user perspective, it is natural to expect the internal Mooncake transport to use the same reachable interface unless explicitly overridden.

However, Mooncake/vLLM uses an auto-detected IP for worker-to-worker KV transfer, which may differ from the HTTP-facing IP on multi-NIC hosts.

Actual behavior

• HTTP endpoints work
• Proxy works
• Mooncake KV transfer fails because the decode worker advertises the wrong IP to the prefill worker
• Error message is not very actionable:

  Mooncake transfer engine returned -1

Expected behavior

At minimum, vLLM should make this easier to diagnose when VLLM_HOST_IP is unset.

Possible improvements:

1. Warn when multiple candidate non-loopback IPs are detected.
2. Log the selected host IP more prominently.
3. Include the selected remote_session / advertised host IP in transfer failure logs.
4. Potentially prefer a more user-visible/configured address when possible, or provide a dedicated explicit CLI/config option for the Mooncake advertise address.

For example, a warning like:

Detected multiple candidate host IPs: ...
Selected 192.168.30.10 for KV transfer.
Set VLLM_HOST_IP to override.

would have made this issue much easier to understand.

Before submitting a new issue...

• Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.