[DOCS] Prompt caching docs omit the startup warning shown when `DISABLE_PROMPT_CACHING*` disables caching

[coygeek]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

The DISABLE_PROMPT_CACHING* environment variable entries and the prompt-caching configuration guidance that explains what users should expect at startup when those variables disable caching

Current Documentation

The environment variable reference currently says:

DISABLE_PROMPT_CACHING | Set to 1 to disable prompt caching for all models (takes precedence over per-model settings)

DISABLE_PROMPT_CACHING_HAIKU | Set to 1 to disable prompt caching for Haiku models

DISABLE_PROMPT_CACHING_OPUS | Set to 1 to disable prompt caching for Opus models

DISABLE_PROMPT_CACHING_SONNET | Set to 1 to disable prompt caching for Sonnet models

The model configuration page currently says:

Claude Code automatically uses prompt caching to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:

DISABLE_PROMPT_CACHING | Set to 1 to disable prompt caching for all models (takes precedence over per-model settings)

The provider setup pages also tell users they can turn caching off:

Optional: Disable prompt caching if needed

export DISABLE_PROMPT_CACHING=1

I could not find any code.claude.com page that documents the startup warning Claude Code now shows when prompt caching has been disabled through these environment variables.

What's Wrong or Missing?

Changelog v2.1.108 says:

Added a warning at startup when prompt caching is disabled via DISABLE_PROMPT_CACHING* environment variables

The docs currently explain how to disable prompt caching, but they do not explain the new user-visible consequence: Claude Code now surfaces a startup warning when any of the DISABLE_PROMPT_CACHING* variables disables caching.

That leaves the documentation incomplete in two practical ways:

A. The startup warning is undocumented

Users who intentionally disable prompt caching for debugging, cost testing, or provider-specific behavior are not told that a warning at launch is now expected behavior.

B. The trigger conditions are undocumented

The docs do not explain that this warning can be triggered by the whole DISABLE_PROMPT_CACHING* family, not just the global DISABLE_PROMPT_CACHING variable.

Suggested Improvement

Update the prompt-caching documentation anywhere DISABLE_PROMPT_CACHING* is introduced so it also documents the startup warning behavior added in v2.1.108.

Suggested minimum fix:

• In env-vars, add a short note near the DISABLE_PROMPT_CACHING* entries explaining that Claude Code shows a startup warning when these variables disable prompt caching
• In model-config, add the same caveat in the prompt-caching configuration section
• In provider setup pages that show export DISABLE_PROMPT_CACHING=1, add a brief note that a startup warning is expected after launch when caching is disabled this way

Suggested wording:

When prompt caching is disabled via DISABLE_PROMPT_CACHING or one of the model-specific DISABLE_PROMPT_CACHING_* variables, Claude Code shows a startup warning so you know caching-related cost and latency optimizations are off.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/env-vars	Primary reference for DISABLE_PROMPT_CACHING*, but it does not mention the startup warning
https://code.claude.com/docs/en/model-config	Prompt caching configuration section lists disable controls without the new startup-warning behavior
https://code.claude.com/docs/en/amazon-bedrock	Bedrock setup example tells users to export DISABLE_PROMPT_CACHING=1 without explaining the expected warning
https://code.claude.com/docs/en/google-vertex-ai	Vertex setup includes the same disable guidance without the warning behavior

Total scope: 4 pages affected

Source: Changelog v2.1.108

Exact changelog entry:

Added a warning at startup when prompt caching is disabled via DISABLE_PROMPT_CACHING* environment variables

[coygeek]

Just checked the current docs again. This issue is not fully resolved yet.

[coygeek]

Still relevant as of 2026-05-28. I checked the current docs and this documentation gap still appears unresolved.

[coygeek]

Verified against the latest docs; this still appears unresolved.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.