llama-server Context Checkpoints: Stop Full Prompt Re-processing on Qwen3.6, Gemma 4 and Other Hybrid/SWA Models

Read time: ~12 minutes. What you’ll learn: what actually happens inside llama-server when it prints forcing full prompt re-processing due to lack of cache data, why the warning only shows up on sliding-window (SWA) and hybrid/recurrent models such as the Qwen3.5/3.6 A3B family and Gemma 4 MoE, how context checkpoints decide whether your cache survives, and which official flags (--ctx-checkpoints, --checkpoint-min-step, --swa-full, --cache-ram, --slot-save-path) change the outcome.

Sourcing note: every flag and default below is quoted from the llama.cpp server README and common/arg.cpp on master as of October 15, 2026; behavior claims come from tools/server/server-context.cpp and the linked GitHub issues and pull requests. No speed numbers are invented. Run llama-server --help on your own build before copying a command, because these flags have been renamed before.

This guide is the deep dive behind one log line. If you only want the general prompt-cache flags for an ordinary transformer (--cache-reuse, --cache-ram, slot persistence), start with our llama-server KV cache reuse guide. This page is for the case where you have already done that and a specific model still re-prefills the whole conversation on every turn.

The short answer

forcing full prompt re-processing due to lack of cache data
(likely due to SWA or hybrid/recurrent memory, see https://github.com/ggml-org/llama.cpp/pull/13194#issuecomment-2868343055)

The message means: your new prompt diverged from the cached one at some position, this model cannot rewind its memory to that position, and the server found no saved context checkpoint early enough to restart from. So it throws the slot’s state away and processes the prompt from token 0.

Ordinary transformer KV caches can be truncated at any position. Two families cannot:

  • SWA (sliding window attention) models only keep the last window of tokens for their SWA layers, so the KV for older positions is already gone.
  • Hybrid / recurrent models (for example the Gated DeltaNet + attention layout used by Qwen3.5/3.6 MoE, and Qwen3-Next) keep a running recurrent state that summarizes everything so far. You can’t “subtract” tokens from it.

For both, the only way to resume from an earlier point is a context checkpoint: a snapshot of the non-rewindable part of the memory taken at a specific position. Fixing the warning is almost always about making sure a usable checkpoint exists before the point where your prompts diverge.

Practical checklist, in order:

  1. Update llama.cpp. Checkpoint handling has changed a lot in 2026 (details below), including an October 8 fix for slot save/restore.
  2. Stop your client from rewriting earlier parts of the conversation (timestamps in the system prompt, re-ordered tool definitions, trimmed reasoning).
  3. Keep --ctx-checkpoints above zero (default 32) and consider lowering --checkpoint-min-step (default 8192) for long agent sessions.
  4. For SWA-only models, try --swa-full if you can spare the memory. It does not help hybrid/recurrent models.
  5. Give the RAM prompt cache room with --cache-ram if several conversations share one server.

The rest of this article explains why each step works, so you can tell which one applies to your log.

1. Where the message comes from

The line lives in tools/server/server-context.cpp. When a new task arrives on a slot, the server computes n_past, the length of the common prefix between the cached tokens and the new prompt. For a normal model it just removes everything after n_past and continues.

For models with SWA or recurrent memory, it first asks the memory module for the smallest position it still holds for that sequence (pos_min) and compares it with a threshold:

const auto pos_min_thold = std::max(0, pos_next - n_swa - (has_new_tokens ? 0 : 1));

If the memory no longer covers the position the server needs to restart from (pos_min >= pos_min_thold), the server searches the slot’s list of context checkpoints, newest first, for one that starts early enough. If it finds one it restores it and logs restored context checkpoint (...). If it does not, it logs the warning and resets n_past to 0.

Two consequences follow directly from that code:

  • It is not an error and nothing crashes. You simply pay full prefill. On a long agent context that can be minutes per turn, which is why people notice it.
  • Divergence is the trigger. If each request strictly appends to the previous prompt, there is nothing to rewind and the warning never appears. The question is always “what changed earlier in my prompt?”

You may not see the line on recent builds

On current master the message is emitted with SLT_TRC, i.e. at trace level. The README documents the log levels for -lv, --verbosity, --log-verbosity N: 0 generic, 1 error, 2 warning, 3 info, 4 trace, 5 debug, with a default of 3. So on a default launch you may only notice the symptom (slow time to first token, high prompt_n in the response timings) and not the message itself. To see it:

llama-server -m your-model.gguf -lv 4

The same trace level shows context checkpoints enabled, max = N, min spacing = M at startup and a created context checkpoint X of N (...) line each time one is made, which is the fastest way to confirm checkpoints are actually being created for your model.

Find exactly where your prompts diverge

The server has a debugging switch for this read from the environment: LLAMA_SERVER_SLOTS_DEBUG. When it is set to a non-zero value and the cached and new prompts differ, the server prints the tokens on both sides of the mismatch (old: ... | ... and new: ... | ...) as warnings:

LLAMA_SERVER_SLOTS_DEBUG=1 llama-server -m your-model.gguf -lv 4

If the | marker lands inside your system prompt, a tool schema, or an earlier assistant message, your client is rewriting history and no server flag will fully fix it.

2. Which models trigger it

The warning is architecture-specific. Reports in the llama.cpp tracker line up with this:

  • Issue #21831 was opened with Qwen3.5-35B-A3B and Gemma-4-26B-A4B. The reporter’s later testing across several models concluded that the full re-processing was specific to hybrid architectures such as qwen35moe, and that pure transformer models like qwen2 cached correctly. The issue was closed as “not planned” on September 29, 2026, after workarounds were posted.
  • Issue #24055, “Context checkpoints always invalidated on hybrid/recurrent models”, is still open and collects reports from Qwen3.6-27B and Qwen3.6-35B-A3B users.
  • PR #28007 describes qwen3_5_moe as Gated DeltaNet layers plus attention, where the recurrent memory can refuse a partial rollback.
  • Issue #28194 measured Qwen3.8-27B (qwen35) as 16 full-attention layers plus 48 Gated DeltaNet layers, and lists Qwen3-Next, Qwen3.5 and Qwen3.8 as hybrid.

A rough mental model:

Model memory typeCan rewind to any position?Needs a checkpoint to resume after divergence?
Plain transformer (full attention only)YesNo
SWA / interleaved SWA (e.g. Gemma family)Only within the windowYes, unless --swa-full
Hybrid / recurrent (e.g. Qwen3.5/3.6/3.8 hybrids, Qwen3-Next)NoYes, always

If you run Qwen3.6 locally for coding, as in our Qwen 3.6 local coding guide, you are squarely in the third row, and multi-turn agent loops are exactly the workload that diverges most.

3. How context checkpoints are created

Knowing when the server takes a snapshot explains most “why did it re-prefill this time?” questions. From server-context.cpp on current master:

Checkpoints are only made when they are needed. The code enables them for completion tasks when --ctx-checkpoints is above zero and the model either cannot remove a partial sequence, can only do so up to a fixed bound (recurrent), or uses SWA. A pure transformer never pays the checkpoint cost.

They are taken at user-message boundaries. While feeding a prompt, the server breaks the batch at the start of a user message when it is the last user message, when there are no checkpoints yet, or when the position is more than --checkpoint-min-step tokens past the previous checkpoint. A checkpoint is created at that break.

Two more are taken near the end of the prompt. Since PR #20288 (merged March 10, 2026), the server processes the tail of the prompt separately so it can snapshot 4 + n_ubatch tokens and 4 tokens before the end. The PR explains the trade-off: re-processing the last few hundred tokens can be too slow in some cases, but some room is needed so the last user message can be edited.

The list is capped. Each slot keeps at most --ctx-checkpoints snapshots; older ones are dropped first.

That design is why the most common real-world triggers are:

  • Editing or regenerating an earlier turn. The divergence point is before the last checkpoint that still matches.
  • A client that mutates history: a timestamp in the system prompt, tool lists that change order, or front-ends that strip previous reasoning blocks before resending. Each changes tokens near the start, where there may be no checkpoint at all except at position 0.
  • Long single-shot pastes followed by edits inside the same message. Checkpoints are anchored to user-message starts, not arbitrary token positions.
  • A request that lands on a different slot than the one holding your conversation. This is not checkpoint-specific, but it looks identical in the logs. See our guide to parallel slots and multiple users for how slots are assigned.

The checkpoint flag history (why old advice breaks)

Advice on forums is often out of date because the flags changed:

  • PR #15293 (merged August 2025) introduced “SWA checkpoints” with a default of 3 per slot, configured with --swa-checkpoints N.
  • Today the README lists -ctxcp, --ctx-checkpoints, --swa-checkpoints N: “max number of context checkpoints to create per slot (default: 32)”. --swa-checkpoints survives as an alias.
  • A workaround posted in #21831 used --checkpoint-every-n-tokens 1024 together with --ctx-checkpoints 256. A commenter noted it had earlier been renamed from --checkpoint-every-nb. Neither name appears in common/arg.cpp on current master. The reporter of #24055 says they were forced onto the new flag starting with the b9354 Docker image.
  • The current spacing control is -cms, --checkpoint-min-step N: “minimum spacing between context checkpoints in tokens (default: 8192, 0 = no minimum)”, environment variable LLAMA_ARG_CHECKPOINT_MIN_SPACING_NT.
  • PR #22929, “server: fix checkpoints creation”, merged May 25, 2026. Commenters on #24055 attribute the change to checkpoints mostly landing at the last message to that PR, which is why some users saw more re-processing after upgrading in mid-2026.

If you copied a launch line containing --checkpoint-every-n-tokens and your build rejects it, that is expected. Replace it with --checkpoint-min-step. Note that the two are not identical: the old flag forced checkpoints during prefill every N tokens, while the new one sets the minimum spacing between checkpoints taken at user-message boundaries.

4. Fixes, from cheapest to most expensive

Fix 1: Update llama.cpp

This matters more than any flag. Checkpoint code changed repeatedly in 2026, and several relevant fixes have landed:

  • Slot save/restore now keeps checkpoints. PR #26004, “server : preserve context checkpoints across slot save/restore”, was merged on October 8, 2026. Before it, restoring a slot rebuilt the token list but not the checkpoints, so the next divergent prompt on an SWA or hybrid model hit the warning even with a long shared prefix. The PR appends the checkpoints to the slot save file. Release b11560 and later include it; check with llama-server --version.
  • Several related PRs are still open at the time of writing, so don’t assume they are in your build: #28007 (fall back cleanly to full re-processing when a recurrent rollback fails instead of aborting or keeping stale state), #24035 (preserve reusable checkpoints for recurrent/hybrid prompts after divergence), and #24785 (recurrent state shrink/expand for the prompt cache, written for Qwen3.6 on ROCm).

Before tuning anything, reproduce the problem on a current build. A good chunk of the reports in #21831 and #24055 were filed against builds that are now months old.

Fix 2: Stop rewriting the prompt prefix

Because every hybrid-model resume depends on a checkpoint before the divergence point, the most reliable fix is making the prompt append-only:

  • Keep the system prompt byte-for-byte stable. Move dynamic data like the current date into the latest user message.
  • Send tool definitions in a fixed order.
  • If your front-end drops earlier reasoning or tool outputs to save context, be aware that each drop shifts everything after it, and the cache from that point on is lost.
  • Avoid regenerating old turns in long sessions if prefill time matters.

Use LLAMA_SERVER_SLOTS_DEBUG=1 from section 1 to prove where the mismatch is. If it is at the very top of the prompt, no checkpoint setting can help, since the only checkpoint that precedes it is position 0.

Fix 3: Tune --ctx-checkpoints and --checkpoint-min-step

If divergence happens deep into a long conversation (for example a coding agent that edits its plan a few turns back), more and denser checkpoints raise the chance one sits just before the edit:

llama-server \
  -m your-hybrid-model.gguf \
  -c 65536 \
  --ctx-checkpoints 64 \
  --checkpoint-min-step 2048 \
  -lv 4
  • --ctx-checkpoints raises the per-slot cap from the default 32.
  • --checkpoint-min-step lowers the minimum spacing from the default 8192 tokens, so user-message boundaries closer together each get a snapshot. 0 removes the minimum.

The cost is memory. Each checkpoint holds the non-rewindable state: for SWA models, PR #15293 says only the SWA part is stored, so a checkpoint is “relatively small (proportional to the SWA window)”. For hybrid models it holds the recurrent state. The created context checkpoint trace line prints each one’s size in MiB, so measure it on your model rather than guessing, and multiply by your cap and slot count.

Setting --ctx-checkpoints 0 disables checkpoints entirely. On an SWA or hybrid model, that guarantees the warning on any divergence.

Some users in #24055 report that tuning alone did not stop re-processing on Qwen3.6 with their builds. If you see created context checkpoint lines but still get the warning, compare the checkpoint positions in the log with the mismatch position from LLAMA_SERVER_SLOTS_DEBUG. If the mismatch is earlier than every checkpoint, you’re back to Fix 2.

Fix 4: --swa-full (SWA models only)

The README lists --swa-full as “use full-size SWA cache (default: false)” and links to the PR #13194 discussion. There, a maintainer describes the choice: the old full cache uses more memory but supports advanced caching, while the new SWA cache uses less memory and supports only last-prefix caching.

With --swa-full, the SWA layers keep their KV for the whole context, so they can be truncated like a normal cache. The server’s checkpoint logic explicitly excludes this case (“the model uses SWA (and we are not using swa_full)”).

llama-server -m your-swa-model.gguf -c 32768 --swa-full

Two caveats:

  • Memory goes up, because the SWA layers now store the full context instead of a window. How much depends on the model’s layer mix and your -c. Check the KV buffer size the server prints at startup with and without the flag. We don’t quote a figure because it varies by model.
  • It does not fix hybrid/recurrent memory. The recurrent state still cannot be rewound. A commenter on #24055 reported that --swa-full made no difference on the Qwen3.6 35B A3B model, which matches the code: the recurrent part still needs checkpoints.

Fix 5: Give the prompt cache room with --cache-ram

Checkpoints live with the slot’s prompt state. When a slot is reused for another conversation, the server can save the idle slot into the RAM prompt cache and bring it back later. The README documents:

  • -cram, --cache-ram N: “set the maximum cache size in MiB (default: 8192, 0 for decision models, -1 - no limit, 0 - disable)”.
  • --cache-idle-slots, --no-cache-idle-slots: “save idle slots to the prompt cache on new task, and clear them when using unified KV (default: enabled, requires cache-ram)”.

Hybrid states plus their checkpoints are bigger than a plain token list. If you serve several long conversations from one server and they come back cold, raise the limit:

llama-server -m your-hybrid-model.gguf -c 65536 -np 2 --cache-ram 16384

(-np, --parallel N sets the number of slots; the default -1 means auto.) The October 15, 2026 change PR #30498 also stopped rerank and embedding requests from filling this cache with states that can never be reused. That helps if one server handles mixed traffic.

Fix 6: Persist across restarts with --slot-save-path

For a long, fixed prefix (an agent’s system prompt plus tool definitions), you can save a warmed slot to disk and restore it after a restart:

llama-server -m your-hybrid-model.gguf --slot-save-path ./slots

curl -X POST "http://localhost:8080/slots/0?action=save" \
  -H "Content-Type: application/json" -d '{"filename": "agent-prefix.bin"}'

curl -X POST "http://localhost:8080/slots/0?action=restore" \
  -H "Content-Type: application/json" -d '{"filename": "agent-prefix.bin"}'

Until PR #26004, this was a trap for exactly the models in this article. Issue #28194 measured a pure-attention model reusing 8,007 of 8,011 tokens after restore, while the hybrid model reused 0, even though the restore returned HTTP 200 and n_restored == n_saved. The cause was that checkpoints weren’t written to the save file. On a build that includes #26004, checkpoints travel with the file. Two notes from the current source:

  • Checkpoints restored from a file are marked as “not created by a task”. If one fails to load, the server logs failed to load context checkpoint restored from a slot file and falls back to full re-processing instead of aborting.
  • A slot file saved by an older build has no checkpoint appendix, so re-save your slots after upgrading.

Issue #28194 itself was still open on October 15, 2026, so verify the fix on your model: restore, resend the same prompt, and check the response’s timings for cache_n and prompt_n.

5. A diagnosis walkthrough

Here is a repeatable way to go from “it’s slow every turn” to a specific cause:

  1. Confirm the build. llama-server --version. If it predates October 8, 2026 and you use slot restore, upgrade first.
  2. Launch with trace logs and slot debugging: 
    LLAMA_SERVER_SLOTS_DEBUG=1 llama-server -m model.gguf -c 32768 -lv 4
  3. Check startup. Look for context checkpoints enabled, max = 32, min spacing = 8192 (or your values). If it says context checkpoints disabled, something set --ctx-checkpoints 0.
  4. Send two turns from your real client. On the first, you should see created context checkpoint lines on SWA or hybrid models. None on a plain transformer is normal.
  5. On the second turn, read the outcome. One of three things will appear:
    • nothing special and a small prompt_n: the prefix was reused, all good.
    • restored context checkpoint (pos_min = ..., pos_max = ..., n_tokens = ...): some re-processing from that checkpoint, which is expected after an edit.
    • forcing full prompt re-processing ...: no usable checkpoint. Look at the old: / new: mismatch lines right above it.
  6. Match the mismatch to a fix:
    • Mismatch near the top of the prompt → client is rewriting history (Fix 2).
    • Mismatch deep in the conversation, checkpoints too sparse → Fix 3.
    • SWA model with spare VRAM → Fix 4.
    • Only after switching between conversations → Fix 5.
    • Only after a restart or restore → Fixes 1 and 6.

For measuring whether a change actually reduced time to first token, see our streaming latency measurement guide. Measure, don’t assume a faster second request means a cache hit.

6. Quick decision table

SituationModel typeWhat to try
Warning on every turn, even plain appendsHybrid (Qwen3.5/3.6 A3B etc.)Upgrade; check a checkpoint is created on turn 1 at -lv 4; check the client isn’t mutating the system prompt
Warning only after editing an older messageAny SWA/hybridExpected unless a checkpoint precedes the edit; lower --checkpoint-min-step, raise --ctx-checkpoints
Warning on Gemma-style SWA model, VRAM availableSWA--swa-full
Warning after /slots restoreSWA/hybridBuild with PR #26004 (b11560+), re-save slot files
Old conversations come back coldAnyRaise --cache-ram; keep --cache-idle-slots on
Launch line rejects --checkpoint-every-n-tokensAnyRemoved on current master; use --checkpoint-min-step
Plain transformer re-prefillingTransformerNot this warning; see the KV cache reuse guide (--cache-reuse)

FAQ

Why does llama-server reprocess the whole prompt on Qwen3.6? Because the Qwen3.5/3.6 hybrids keep a recurrent state that can’t be rolled back to an arbitrary position. When your new prompt differs from the cached one before the latest usable context checkpoint, the server has to start from zero. Make prompts append-only and make sure checkpoints are being created.

Does --cache-reuse work with SWA or hybrid models? --cache-reuse N reuses cached chunks “via KV shifting” and requires prompt caching (default 0, off). Shifting assumes the cache can be moved and truncated freely, which is what SWA and recurrent memory can’t do. On these models, rely on checkpoints and append-only prompts, not --cache-reuse.

What does --swa-full do, and what does it cost? It allocates a full-size cache for the SWA layers (default false), which allows them to be truncated like a normal KV cache. The cost is more KV memory, scaling with context length and the number of SWA layers. Compare the startup KV buffer sizes on your model. It has no effect on recurrent state.

Is the warning a bug? Usually it’s correct behavior: the server has no state to resume from. Some cases have been genuine bugs, like checkpoints lost on slot restore before PR #26004, or the open reports in #24055. So upgrade and re-test before tuning.

Why can’t I see the message even though prefill is slow? On current master it is logged at trace level. Start the server with -lv 4.

Is --checkpoint-every-n-tokens still a thing? Not on current master. The spacing control is now -cms, --checkpoint-min-step N (default 8192, 0 = no minimum).

Sources