[KV Offload] Explain missing chunks when prepare_load fails

[nadongjun]

Overview

Adds a bounded eviction history and the missing keys' token positions to the assertion message CPUOffloadingManager.prepare_load() raises for a missing chunk. This is evidence for investigating a coverage mismatch or an eviction between lookup() and the load. It doesn't identify either cause on its own. Behavior is unchanged. Related: #54914, #56701.

Claims

• The failure message lists (end_token, seconds since its last recorded eviction) for up to 16 missing keys. It also gives the end_token range of the whole load, the KV group and the request ID.
• Evicted keys are kept in a bounded history: 10,000 keys, about 1.5 MiB, one time.monotonic() call per eviction batch. The message is built only when the assertion fails, and nothing is logged otherwise.
• No behavior change: the same assertion fires in the same places.

Validation

pytest tests/v1/kv_offload/cpu/test_manager.py tests/v1/kv_offload/tiering
pre-commit run --files vllm/v1/kv_offload/cpu/manager.py tests/v1/kv_offload/cpu/test_manager.py

• Messages produced by this change:

# Stored, hit by lookup(), evicted by another store before prepare_load():
... not found in cache (group=5, req_id='req-a'). 1 of 1 keys in this load are missing. (end_token, seconds since eviction) per missing key: [(1024, 0.0)]; load end_token range: 1024-1024; eviction history: 1 keys over 0.0s.

# First chunk of the load never stored:
... not found in cache (group=5, req_id='req-b'). 1 of 4 keys in this load are missing. (end_token, seconds since eviction) per missing key: [(1024, None)]; load end_token range: 1024-1792; eviction history: 0 keys over 0.0s.

These were run on CPU only (macOS). I did not reproduce the assertion end to end on GPU: the change only builds the message after the assertion has already failed. The new tests run in the existing tests/v1/kv_offload CI step.

Details

Motivation. Two different defects end in this assertion:

1. Coverage mismatch. The load asks for a chunk that was never stored, because lookup/store and load disagree on the range. The MTP retained window ([RFC][KV Offload]: Align sliding-window restore coverage with MTP-retained history #56701, fixed by [Bugfix][KV Offload] Restore MTP-retained sliding-window history #56709 in v0.31.0) is one case.
2. Eviction after lookup. The chunk was stored and lookup() returned a hit, but it was evicted before prepare_load() pinned it. Tiering promotions evict primary-tier chunks from inside lookup() (see [Bugfix][KV Offload] Protect unread promotions from eviction by other speculative promotions #50014), so another request's lookup in the same scheduler pass can evict a chunk that was already reported as a hit.

Today's message is just the key, so the reports can't tell (1) from (2):

• [Bug]: KV Cache Offloading AssertionError after several days of uptime with DeepSeek-V4-Pro on 3×8 H100 (TP8+DP3) #54914 has two reports of this assertion, from the author and one other user, after hours to days of uptime.
• We hit it twice in production on v0.30.0, both on KV group 5, with Gemma 4, MTP3 and CPU + filesystem tiering. After going through all the logs we could only conclude that the offload bookkeeping invariant broke.

How to read it. These are clues to narrow the investigation, not proof of a cause:

• An eviction age means the key had a recorded eviction that long ago. It points toward (2) when it is recent. The lookup time isn't recorded, so it doesn't prove the eviction happened between lookup() and the load. For example, a key evicted, re-inserted, and then dropped by a failed store still shows the age of the earlier eviction.
• None means there is no recorded eviction for the key. It is not proof that the key was never stored: the eviction may be older than the history, and removals by complete_store(success=False) aren't recorded. A run of None keys at one edge of the load range fits (1).

Why not fix the race here. Fixing (2) means keeping lookup hits from being evicted until the load is prepared, or revalidating them safely before the load is committed. Manager locking (#58168) handles concurrent access, but it doesn't stop an eviction on the same thread, such as another request's promotion in the same scheduler pass. That fix changes scheduling and belongs in a separate PR. This change gives it data.

Not a duplicate. No open PR changes this message. The open PRs in this area are fixes, not diagnostics:

• [KV Offload] Expose OffloadingManager.lock()/unlock() and service the tiering control plane off the scheduler thread #58168 adds manager locking.
• [Bugfix][KV Offload] Protect unread promotions from eviction by other speculative promotions #50014 protects unread promotions from eviction.

Limitations.

• The history covers only the last 10,000 evictions. Under heavy eviction that can be a few seconds, and an older eviction shows as None. EVICTION_HISTORY_SIZE is a class attribute and can be raised.
• Removals after a failed store aren't recorded, and neither is the lookup time.
• Only the first 16 missing keys are listed.

---

Pull Request Checklist

• I used vLLM's /pr-checklist skill. (Mandatory for agents, optional for humans).

• AI assistance was used during the creation of this PR.

• Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

• Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI.

• Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.

• Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Reviewers with write access and configured trusted contributors can comment /ci run for upstream CI or /amd-ci run for AMD CI only whenever CI signals are needed.

Once the PR is approved or has the ready label, the PR author can also use the corresponding /ci run, /ci retry, and /ci cancel commands, or their /amd-ci variants. New commits do not start upstream CI automatically.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀