[GH-ISSUE #4350] [Documentation]: [TransferEngine] GPU memory registration fails with "Bad address" on DMA-BUF-only hosts: `WITH_NVIDIA_PEERMEM` defaults to true, with no fallback or hint #1090

New issue

Closed

opened 2026-10-29 21:22:47 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-29 21:22:47 +00:00

Owner

Originally created by @cloudomate on GitHub (Sep 28, 2026).
Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/4350

Documentation Feedback

Hi Mooncake team, and thanks for the DMA-BUF registration path. It works well for us once enabled. We lost some time finding out that it has to be enabled explicitly, so here are a few suggestions that may help others.

Environment

Mooncake mooncake-transfer-engine-cuda13==0.3.13.post1 (PyPI) in a CUDA 13.0 image; also checked current main (16b7ba3)
H200 in MIG mode (3g.71gb and 1g.18gb GPU instances), ConnectX-7 over RoCE
NVIDIA open kernel modules 570.172.08; kernel 6.8; inbox RDMA stack (no MLNX_OFED)
No nvidia-peermem: GPU Operator with driver.rdma.enabled=false. Per NVIDIA's GPU Operator docs, peermem needs MLNX_OFED/DOCA-OFED, while DMA-BUF only needs the open kernel modules and Linux ≥ 5.12.
Client: vLLM MooncakeStoreConnector (standalone store), which registers its GPU KV cache

What happens

vLLM starts and the connector registers the GPU KV cache:

rdma_context.cpp:602] Failed to register memory 0x78f966000000: Bad address [14]
worker.py:1848] register_buffer failed for addr 0x78f966000000 len 35246833664: -600

Every later put then fails:

rdma_transport.cpp:955] Memory region not registered by any active device(s): 0x78f966c40000
transfer_task.cpp:1252] Failed to submit all transfers, error code is AddressNotRegistered

Nothing in the logs points at WITH_NVIDIA_PEERMEM. The engine keeps serving, so the only visible symptom is that nothing is ever stored.

Root cause

mooncake-common/src/environ.cpp:201 reads the variable with a default of true:

with_nvidia_peermem_ = ReadBool(source, "WITH_NVIDIA_PEERMEM", true);

So RdmaContext::exportDmabuf picks kHostReg, and GPU memory goes to plain ibv_reg_mr(). That call needs nvidia-peermem and fails with EFAULT without it.

Setting WITH_NVIDIA_PEERMEM=0 fixes it completely. We checked with a small probe on the same MIG slice:

Check	Result
`CU_DEVICE_ATTRIBUTE_DMA_BUF_SUPPORTED`	1
`cuMemGetHandleForAddressRange(DMA_BUF_FD)`	OK
`ibv_reg_mr` on the GPU buffer	EFAULT
`ibv_reg_dmabuf_mr` (with and without `IBV_ACCESS_RELAXED_ORDERING`)	OK
`TransferEngine.register_memory` on the GPU buffer	−202 by default, 0 with `WITH_NVIDIA_PEERMEM=0`

Documentation

The 0.3.13.post1 docs (docs/source/design/transfer-engine/index.md) say "By default (unset or 0), Mooncake uses the DMA-BUF path". That was the opposite of the code for the release we ran. We see main has since corrected the English page, thank you.
docs/source/zh_archive/transfer-engine.md:427 and docs/sorce/zh_archive/run-examples.md:42 on main still say the default is DMA-BUF.

Suggestions (any one would have saved us the debugging; your call which fits best)

Fallback: when ibv_reg_mr() on device memory fails with EFAULT while WITH_NVIDIA_PEERMEM is unset (not explicitly 1), retry once through the DMA-BUF export. If DMA-BUF also fails, report both errors.
Auto-detect: when the variable is unset, choose DMA-BUF if nvidia_peermem isn't loaded (/sys/module/nvidia_peermem absent) and the device reports DMA_BUF_SUPPORTED=1.
Actionable error: at minimum, when device memory registration fails through ibv_reg_mr, log a hint such as "GPU memory registered via ibv_reg_mr (WITH_NVIDIA_PEERMEM unset/true), which requires nvidia-peermem; set WITH_NVIDIA_PEERMEM=0 to use DMA-BUF." An INFO line at startup saying which registration path is in use would also help.

Before submitting a new issue...

Make sure you already searched for relevant issues and read the documentation

Originally created by @cloudomate on GitHub (Sep 28, 2026). Original GitHub issue: https://github.com/kvcache-ai/Mooncake/issues/4350 ### Documentation Feedback Hi Mooncake team, and thanks for the DMA-BUF registration path. It works well for us once enabled. We lost some time finding out that it has to be enabled explicitly, so here are a few suggestions that may help others. **Environment** - Mooncake `mooncake-transfer-engine-cuda13==0.3.13.post1` (PyPI) in a CUDA 13.0 image; also checked current `main` (`16b7ba3`) - H200 in MIG mode (`3g.71gb` and `1g.18gb` GPU instances), ConnectX-7 over RoCE - NVIDIA open kernel modules 570.172.08; kernel 6.8; inbox RDMA stack (no MLNX_OFED) - **No `nvidia-peermem`**: GPU Operator with `driver.rdma.enabled=false`. Per NVIDIA's GPU Operator docs, peermem needs MLNX_OFED/DOCA-OFED, while DMA-BUF only needs the open kernel modules and Linux ≥ 5.12. - Client: vLLM `MooncakeStoreConnector` (standalone store), which registers its GPU KV cache **What happens** 1. vLLM starts and the connector registers the GPU KV cache: ``` rdma_context.cpp:602] Failed to register memory 0x78f966000000: Bad address [14] worker.py:1848] register_buffer failed for addr 0x78f966000000 len 35246833664: -600 ``` 2. Every later put then fails: ``` rdma_transport.cpp:955] Memory region not registered by any active device(s): 0x78f966c40000 transfer_task.cpp:1252] Failed to submit all transfers, error code is AddressNotRegistered ``` 3. Nothing in the logs points at `WITH_NVIDIA_PEERMEM`. The engine keeps serving, so the only visible symptom is that nothing is ever stored. **Root cause** `mooncake-common/src/environ.cpp:201` reads the variable with a default of `true`: ```cpp with_nvidia_peermem_ = ReadBool(source, "WITH_NVIDIA_PEERMEM", true); ``` So `RdmaContext::exportDmabuf` picks `kHostReg`, and GPU memory goes to plain `ibv_reg_mr()`. That call needs `nvidia-peermem` and fails with `EFAULT` without it. Setting `WITH_NVIDIA_PEERMEM=0` fixes it completely. We checked with a small probe on the same MIG slice: | Check | Result | |---|---| | `CU_DEVICE_ATTRIBUTE_DMA_BUF_SUPPORTED` | 1 | | `cuMemGetHandleForAddressRange(DMA_BUF_FD)` | OK | | `ibv_reg_mr` on the GPU buffer | EFAULT | | `ibv_reg_dmabuf_mr` (with and without `IBV_ACCESS_RELAXED_ORDERING`) | OK | | `TransferEngine.register_memory` on the GPU buffer | −202 by default, **0 with `WITH_NVIDIA_PEERMEM=0`** | **Documentation** - The 0.3.13.post1 docs (`docs/source/design/transfer-engine/index.md`) say *"By default (unset or `0`), Mooncake uses the DMA-BUF path"*. That was the opposite of the code for the release we ran. We see `main` has since corrected the English page, thank you. - `docs/source/zh_archive/transfer-engine.md:427` and `docs/sorce/zh_archive/run-examples.md:42` on `main` still say the default is DMA-BUF. **Suggestions (any one would have saved us the debugging; your call which fits best)** 1. **Fallback:** when `ibv_reg_mr()` on device memory fails with `EFAULT` while `WITH_NVIDIA_PEERMEM` is unset (not explicitly `1`), retry once through the DMA-BUF export. If DMA-BUF also fails, report both errors. 2. **Auto-detect:** when the variable is unset, choose DMA-BUF if `nvidia_peermem` isn't loaded (`/sys/module/nvidia_peermem` absent) and the device reports `DMA_BUF_SUPPORTED=1`. 3. **Actionable error:** at minimum, when device memory registration fails through `ibv_reg_mr`, log a hint such as *"GPU memory registered via ibv_reg_mr (WITH_NVIDIA_PEERMEM unset/true), which requires nvidia-peermem; set WITH_NVIDIA_PEERMEM=0 to use DMA-BUF."* An INFO line at startup saying which registration path is in use would also help. ### Before submitting a new issue... - [ ] Make sure you already searched for relevant issues and read the [documentation](https://kvcache-ai.github.io/Mooncake/)

bsakaguchi

2026-10-29 21:22:47 +00:00

closed this issue
added the
documentation
label

bsakaguchi commented

2026-10-29 21:22:48 +00:00

Author

Owner

@github-actions[bot] commented on GitHub (Sep 28, 2026):

Thanks for opening this issue, @cloudomate!

Field	Value
Issue	#4350
GitHub user ID	`38678537`
Reporter	@cloudomate

A maintainer will triage this when possible. To help us respond faster, please include:

Mooncake version or commit SHA
Environment (OS, CUDA/driver, RDMA stack if relevant)
Steps to reproduce and expected vs. actual behavior

Useful links: Documentation · Contributing guide

This message was posted automatically by the issue bot.

@github-actions[bot] commented on GitHub (Sep 28, 2026): Thanks for opening this issue, @cloudomate! | Field | Value | |-------|-------| | **Issue** | #4350 | | **GitHub user ID** | `38678537` | | **Reporter** | @cloudomate | A maintainer will triage this when possible. To help us respond faster, please include: - Mooncake version or commit SHA - Environment (OS, CUDA/driver, RDMA stack if relevant) - Steps to reproduce and expected vs. actual behavior Useful links: [Documentation](https://kvcache-ai.github.io/Mooncake/) · [Contributing guide](https://github.com/kvcache-ai/Mooncake/blob/main/CONTRIBUTING.md) > This message was posted automatically by the issue bot.

bsakaguchi referenced this issue

2026-10-29 21:32:04 +00:00

[PR #1090] [CLOSED] [WIP] Move test-sglang-integration job to standalone workflow file #2008