[DOCS] Prompt caching TTL env var docs omit generic 1-hour and forced 5-minute controls

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Prompt caching environment variables, especially ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M, and the deprecated ENABLE_PROMPT_CACHING_1H_BEDROCK alias

Current Documentation

The env var reference currently documents prompt-caching controls like this:

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 ENABLE_PROMPT_CACHING_1H_BEDROCK | Set to 1 when using Bedrock to request a 1-hour prompt cache TTL instead of the default 5 minutes. Bedrock only

The model configuration page also frames prompt-caching configuration as disable-only:

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

And the documented table there only lists DISABLE_PROMPT_CACHING, DISABLE_PROMPT_CACHING_HAIKU, DISABLE_PROMPT_CACHING_SONNET, and DISABLE_PROMPT_CACHING_OPUS.

The Vertex AI setup page similarly says:

Prompt caching is automatically supported when you specify the cache_control ephemeral flag. To disable it, set DISABLE_PROMPT_CACHING=1.

I could not find any code.claude.com page documenting ENABLE_PROMPT_CACHING_1H, FORCE_PROMPT_CACHING_5M, or that ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored.

What's Wrong or Missing?

Changelog v2.1.108 says:

Added ENABLE_PROMPT_CACHING_1H env var to opt into 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry (ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored), and FORCE_PROMPT_CACHING_5M to force 5-minute TTL

But the current docs still present the older Bedrock-only variable as the documented way to request a longer TTL, and they do not document the new generic controls.

A. The new cross-provider 1-hour TTL variable is missing

Users on API key, Vertex, and Foundry do not have documentation telling them to use ENABLE_PROMPT_CACHING_1H.

B. The forced 5-minute override is missing

There is no documentation for FORCE_PROMPT_CACHING_5M, so users cannot discover that Claude Code now has an env var specifically for forcing the 5-minute TTL.

C. The Bedrock-specific variable is now outdated as primary guidance

ENABLE_PROMPT_CACHING_1H_BEDROCK is still documented as current, Bedrock-only guidance, but the changelog says it is deprecated and only kept for backward compatibility.

Suggested Improvement

Update the prompt-caching env var docs to separate three concerns clearly:

1. Disabling prompt caching entirely (DISABLE_PROMPT_CACHING*)
2. Opting into a 1-hour TTL with ENABLE_PROMPT_CACHING_1H
3. Forcing the default 5-minute TTL with FORCE_PROMPT_CACHING_5M

Suggested minimum fix:

• Add ENABLE_PROMPT_CACHING_1H to env-vars with explicit provider coverage: API key, Bedrock, Vertex, and Foundry
• Add FORCE_PROMPT_CACHING_5M to env-vars
• Change ENABLE_PROMPT_CACHING_1H_BEDROCK to a deprecated-alias entry that says it is still honored but ENABLE_PROMPT_CACHING_1H is preferred
• Update model-config so prompt-caching configuration is not described as disable-only
• Add short provider-page notes or examples on Bedrock, Vertex, and Foundry setup pages showing where TTL selection fits into prompt-caching configuration
• Document how these TTL env vars interact if both are set

Example wording for env-vars:

ENABLE_PROMPT_CACHING_1H | Set to 1 to request a 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry FORCE_PROMPT_CACHING_5M | Set to 1 to force the default 5-minute prompt cache TTL ENABLE_PROMPT_CACHING_1H_BEDROCK | Deprecated alias for ENABLE_PROMPT_CACHING_1H on Bedrock; still honored for backward compatibility

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/env-vars | Primary env var reference still documents only the deprecated Bedrock-specific 1-hour variable |
| https://code.claude.com/docs/en/model-config | Prompt caching configuration section currently documents disable-only controls |
| https://code.claude.com/docs/en/amazon-bedrock | Bedrock setup example mentions disabling prompt caching but not the new generic 1-hour TTL env var or deprecation of the old one |
| https://code.claude.com/docs/en/google-vertex-ai | Vertex setup mentions prompt caching and disable-only guidance, but no TTL override env vars |
| https://code.claude.com/docs/en/microsoft-foundry | Foundry setup page does not document prompt-caching TTL env vars even though v2.1.108 says Foundry supports the new control |
| https://platform.claude.com/docs/en/build-with-claude/prompt-caching | Cross-reference for the underlying 5-minute vs 1-hour prompt-caching TTL concept |

Total scope: 6 pages affected

Source: Changelog v2.1.108

Exact changelog entry:

Added ENABLE_PROMPT_CACHING_1H env var to opt into 1-hour prompt cache TTL on API key, Bedrock, Vertex, and Foundry (ENABLE_PROMPT_CACHING_1H_BEDROCK is deprecated but still honored), and FORCE_PROMPT_CACHING_5M to force 5-minute TTL