cache-diagnostics changedbuild-with-claude/cache-diagnostics
Recorded here
Lines+104added
Lines−71removed
From line
194
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
The whole hunk
from line 194, old and new numbered
/
from line 194
194194 ```
195195
196196 ```csharp C#
197 using Anthropic.Models.Beta;
198 using Anthropic.Models.Beta.Messages;
199 using Messages = Anthropic.Models.Messages;
200
197201 AnthropicClient client = new();
198202
199203 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
from line 295
291295 ```
292296
293297 ```java Java
294 var client = AnthropicOkHttpClient.fromEnv();
298 import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
299 import com.anthropic.models.beta.messages.BetaDiagnosticsParam;
300 import com.anthropic.models.beta.messages.MessageCreateParams;
301 import com.anthropic.models.messages.Model;
295302
296 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
303 void main() {
304 var client = AnthropicOkHttpClient.fromEnv();
297305
298 var r1 = client.beta().messages().create(
299 MessageCreateParams.builder()
300 .model(Model.CLAUDE_OPUS_5_5)
301 .maxTokens(1024)
302 .cacheControl(BetaCacheControlEphemeral.builder().build())
303 .system(system)
304 .addUserMessage("Summarize section 1.")
305 // Pass null on the first turn to opt in without a prior message to compare.
306 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId((String) null).build())
307 .build()
308 );
306 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
309307
310 var r2 = client.beta().messages().create(
311 MessageCreateParams.builder()
312 .model(Model.CLAUDE_OPUS_5_5)
313 .maxTokens(1024)
314 .cacheControl(BetaCacheControlEphemeral.builder().build())
315 .system(system)
316 .addUserMessage("Summarize section 1.")
317 .addMessage(r1)
318 .addUserMessage("Now summarize section 2.")
319 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())
320 .build()
321 );
308 var r1 = client.beta().messages().create(
309 MessageCreateParams.builder()
310 .model(Model.CLAUDE_OPUS_5_5)
311 .maxTokens(1024)
312 .cacheControl(BetaCacheControlEphemeral.builder().build())
313 .system(system)
314 .addUserMessage("Summarize section 1.")
315 // Pass null on the first turn to opt in without a prior message to compare.
316 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId((String) null).build())
317 .build()
318 );
322319
323 if (r2.diagnostics().isEmpty()) {
324 IO.println("No divergence detected.");
325 } else if (r2.diagnostics().get().cacheMissReason().isEmpty()) {
326 IO.println("Comparison still pending.");
327 } else {
328 var reason = r2.diagnostics().get().cacheMissReason().get();
329 IO.println("cache_miss_reason: " + reason.type().asString());
320 var r2 = client.beta().messages().create(
321 MessageCreateParams.builder()
322 .model(Model.CLAUDE_OPUS_5_5)
323 .maxTokens(1024)
324 .cacheControl(BetaCacheControlEphemeral.builder().build())
325 .system(system)
326 .addUserMessage("Summarize section 1.")
327 .addMessage(r1)
328 .addUserMessage("Now summarize section 2.")
329 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())
330 .build()
331 );
332
333 if (r2.diagnostics().isEmpty()) {
334 IO.println("No divergence detected.");
335 } else if (r2.diagnostics().get().cacheMissReason().isEmpty()) {
336 IO.println("Comparison still pending.");
337 } else {
338 var reason = r2.diagnostics().get().cacheMissReason().get();
339 IO.println("cache_miss_reason: " + reason.type().asString());
340 }
330341 }
331342 ```
332343
333344 ```php PHP
345 use Anthropic\Beta\Messages\BetaCacheControlEphemeral;
346 use Anthropic\Beta\Messages\BetaDiagnosticsParam;
347 use Anthropic\Messages\Model;
348
334349 $client = new Client();
335350
336351 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';
from line 772
757772 ```
758773
759774 ```typescript TypeScript
775 import type { BetaMessage, BetaMessageParam } from "@anthropic-ai/sdk/resources/beta";
776
760777 const client = new Anthropic();
761778
762779 const SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>";
from line 807
790807 ```
791808
792809 ```csharp C#
810 using Anthropic.Models.Beta;
811 using Anthropic.Models.Beta.Messages;
812 using Messages = Anthropic.Models.Messages;
813
793814 AnthropicClient client = new();
794815
795816 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
from line 890
869890 ```
870891
871892 ```java Java
872 var client = AnthropicOkHttpClient.fromEnv();
893 import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
894 import com.anthropic.models.beta.messages.BetaDiagnosticsParam;
895 import com.anthropic.models.beta.messages.BetaMessageParam;
896 import com.anthropic.models.beta.messages.MessageCreateParams;
897 import com.anthropic.models.messages.Model;
873898
874 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
875 var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");
899 void main() {
900 var client = AnthropicOkHttpClient.fromEnv();
876901
877 var messages = new ArrayList<BetaMessageParam>();
878 String prevId = null;
902 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
903 var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");
879904
880 for (var turn = 0; turn < prompts.size(); turn++) {
881 messages.add(BetaMessageParam.ofUser(prompts.get(turn)));
905 var messages = new ArrayList<BetaMessageParam>();
906 String prevId = null;
882907
883 var response = client.beta().messages().create(
884 MessageCreateParams.builder()
885 .model(Model.CLAUDE_OPUS_5_5)
886 .maxTokens(1024)
887 .cacheControl(BetaCacheControlEphemeral.builder().build())
888 .system(system)
889 .messages(messages)
890 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())
891 .build()
892 );
908 for (var turn = 0; turn < prompts.size(); turn++) {
909 messages.add(BetaMessageParam.ofUser(prompts.get(turn)));
893910
894 if (response.diagnostics().isPresent() && response.diagnostics().get().cacheMissReason().isPresent()) {
895 var reason = response.diagnostics().get().cacheMissReason().get();
896 IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + reason.type().asString());
897 }
911 var response = client.beta().messages().create(
912 MessageCreateParams.builder()
913 .model(Model.CLAUDE_OPUS_5_5)
914 .maxTokens(1024)
915 .cacheControl(BetaCacheControlEphemeral.builder().build())
916 .system(system)
917 .messages(messages)
918 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())
919 .build()
920 );
898921
899 messages.add(response.toParam());
900 prevId = response.id();
922 if (response.diagnostics().isPresent() && response.diagnostics().get().cacheMissReason().isPresent()) {
923 var reason = response.diagnostics().get().cacheMissReason().get();
924 IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + reason.type().asString());
925 }
926
927 messages.add(response.toParam());
928 prevId = response.id();
929 }
901930 }
902931 ```
903932
904933 ```php PHP
934 use Anthropic\Beta\Messages\BetaCacheControlEphemeral;
935 use Anthropic\Beta\Messages\BetaDiagnosticsParam;
936 use Anthropic\Messages\Model;
937
905938 $client = new Client();
906939
907940 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';
from line 1000
9671000
9681001| Value | Meaning |
9691002| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
970| `null` | The request did not include the `diagnostics` object, `previous_message_id` was `null` (first turn, nothing to compare), or a comparison ran and found no divergence. |
1003| `null` | The request did not include the `diagnostics` object, `previous_message_id` was `null` (first turn, nothing to compare), or nothing diverged before the last breakpoint. |
9711004| `{"cache_miss_reason": null}` | The comparison was still running when the response was serialized. This can occur when the response starts very quickly. Treat it as inconclusive and check the next turn. |
9721005| `{"cache_miss_reason": {...}}` | A `cache_miss_reason` is attached. For `*_changed` types this identifies the first divergence point; `previous_message_not_found` and `unavailable` are cases where no comparison was produced. |
9731006
from line 1050
10171050
10181051This matrix applies to turns where you passed a real `previous_message_id`. On the first turn (`previous_message_id: null`), `diagnostics` is always `null` and `cache_read_input_tokens` is normally zero because the cache is being written, not read; no troubleshooting is needed. The matrix also does not apply when `cache_miss_reason` is `null` (the comparison is still pending; check the next turn) or when its `type` is `previous_message_not_found` or `unavailable` (no comparison was produced).
10191052
1020| Diagnostics result | Cache read tokens | Interpretation |
1021| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1022| `null` | high | Working as expected. Your prefix is stable and the cache hit. |
1023| `null` | low or zero | Your requests match but the cache entry was no longer available. Consider shortening gaps between turns or using the [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). |
1024| `cache_miss_reason` is a `*_changed` type | low or zero | The request changed; fix the cause indicated by `type`. |
1025| `cache_miss_reason` is a `*_changed` type | high | Rare. A change occurred late in the prompt but an earlier `cache_control` breakpoint still hit. Worth fixing, but low impact. |
1053| Diagnostics result | Cache read tokens | Interpretation |
1054| ----------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1055| `null` | high | The cache hit. |
1056| `null` | low or zero | Your requests match, but there was no cache entry to read: it had expired, or the prompt is shorter than the [minimum cacheable length](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations). |
1057| `cache_miss_reason` is a `*_changed` type | low or zero | The request changed; fix the cause indicated by `type`. |
1058| `cache_miss_reason` is a `*_changed` type | high | Rare. A change occurred late in the prompt but an earlier `cache_control` breakpoint still hit. Worth fixing, but low impact. |
10261059
10271060## Limitations
10281061
No line in this hunk matches that.