[KV Connector][NIXL][Bugfix] Fix NIXL handshake failures not honoring kv_load_failure_policy (#40364)

When NIXL handshake fails (e.g., due to compatibility hash mismatch
between prefill and decode instances), requests fail with "engine dead"
error instead of gracefully falling back to local recomputation as configured
by kv_load_failure_policy='recompute'.

Signed-off-by: NickLucche <nlucches@redhat.com>
This commit is contained in:
Nicolò Lucchesi
2026-05-11 09:37:21 +00:00
committed by GitHub
parent 770e9bd6b3
commit 5672d100ed
2 changed files with 162 additions and 25 deletions
@@ -2267,6 +2267,127 @@ def test_transfer_setup_failure_returns_finished(default_vllm_config, dist_init)
assert request_id in done_recving
@patch(
"vllm.distributed.kv_transfer.kv_connector.v1.nixl.worker.NixlWrapper",
FailingNixlWrapper,
)
@pytest.mark.parametrize(
"failure_mode",
[
"handshake",
"transfer_setup",
"transfer_failed",
"transfer_exception",
],
)
def test_failed_request_skips_kv_postprocessing(
default_vllm_config, dist_init, failure_mode
):
"""Test that failed requests skip KV sync and post-processing in
get_finished().
This is the core safety behavior: when a KV transfer fails at any stage,
the request must still appear in done_recving (so the scheduler can apply
kv_load_failure_policy), but sync_recved_kv_to_device and post-processing
must NOT be called since no valid KV data was received.
Covers all failure paths that involve an actual (attempted) KV transfer:
- handshake: add_remote_agent raises during async handshake
- transfer_setup: make_prepped_xfer raises before handle is in transfers
- transfer_failed: check_xfer_state returns bad state ("ERR") in
_pop_done_transfers — this is the path that previously had the bug
where post-processing was NOT skipped
- transfer_exception: check_xfer_state raises in _pop_done_transfers
Note: notification_failed (send_notif raises on the full-cache-hit path)
is intentionally excluded. That path is a best-effort D→P courtesy
notification; the blocks are already in D's cache, so no KV transfer
was attempted and done_recving is correctly empty.
"""
# Map each failure mode to the FailingNixlWrapper attribute to set.
_WRAPPER_CONFIG: dict[str, str] = {
"handshake": "fail_handshake",
"transfer_setup": "fail_transfer_setup",
"transfer_failed": "fail_transfer_state",
"transfer_exception": "fail_transfer_exception",
}
# Use enable_permute_local_kv=True so that
# post_process_device_kv_on_receive would be called on the success path,
# making the assertion meaningful (not trivially true).
vllm_config = create_vllm_config(enable_permute_local_kv=True)
connector = NixlConnector(
vllm_config, KVConnectorRole.WORKER, make_kv_cache_config(block_size=16)
)
connector.connector_worker = FakeNixlConnectorWorker(
vllm_config,
connector.engine_id,
hand_shake_latency=0.1 if failure_mode == "handshake" else 0,
)
worker = connector.connector_worker
setattr(worker.nixl_wrapper, _WRAPPER_CONFIG[failure_mode], True)
request_id = f"test_{failure_mode}_skip_postprocess"
metadata = NixlConnectorMetadata()
metadata.add_new_req_to_recv(
request_id=request_id,
local_block_ids=([1, 2, 3],),
kv_transfer_params={
"remote_block_ids": ([4, 5, 6],),
"remote_engine_id": FakeNixlConnectorWorker.REMOTE_ENGINE_ID,
"remote_request_id": f"prefill-{request_id}",
"remote_host": "localhost",
"remote_port": 1234,
"remote_tp_size": 1,
},
)
connector.bind_connector_metadata(metadata)
dummy_ctx = ForwardContext(
no_compile_layers={},
attn_metadata={},
slot_mapping={},
)
connector.start_load_kv(dummy_ctx)
if failure_mode == "handshake":
# Wait for async handshake to fail.
time.sleep(0.3)
else:
# All other modes: let the handshake complete, then process the
# ready_requests queue. For transfer_failed / transfer_exception the
# handle ends up in _recving_transfers; the failure surfaces in
# get_finished() via _pop_done_transfers below.
connector.bind_connector_metadata(NixlConnectorMetadata())
time.sleep(0.1)
connector.start_load_kv(dummy_ctx)
# Spy on sync_recved_kv_to_device and post_process_device_kv_on_receive
# to verify they are NOT called for the failed request.
with (
patch.object(worker, "sync_recved_kv_to_device") as mock_sync,
patch.object(worker, "post_process_device_kv_on_receive") as mock_postprocess,
):
_, done_recving = connector.get_finished(finished_req_ids=set())
# The failed request must appear in done_recving so the scheduler
# can handle it (e.g., trigger recompute via kv_load_failure_policy).
assert request_id in done_recving
# Critical: KV sync and post-processing must NOT have been called
# since no valid KV data was received for the failed request.
mock_sync.assert_not_called()
mock_postprocess.assert_not_called()
# Metadata for the request should have been cleaned up.
assert request_id not in worker._recving_metadata
# Blocks should have been marked as invalid.
invalid_blocks = connector.get_block_ids_with_load_errors()
assert invalid_blocks == {1, 2, 3}
@pytest.mark.parametrize(
"mismatch_type,config_overrides,version_override,should_fail,enforce_handshake_compat",
[