Codex Says prompt_cache_retention Is Not Supported? Recover Safely

If Codex returns prompt_cache_retention is not supported on this model, first determine whether Codex added the setting or your own API request did. In the Codex app or extension, preserve the task, retry the turn once after a short pause, and check for a service incident before changing local files. In a custom harness, remove the legacy field for GPT-5.6 and later and use the model's documented cache controls instead.

This error is a request and model compatibility failure. It is not evidence that your repository, chat history, authentication, or local cache is corrupt.

Choose the Right Recovery Path

On August 23, 2026, a Codex community report collected six same-window comments about the failure across Codex clients. One commenter reported that the field was absent from the captured client request, and retrying often succeeded. A separate OpenAI Developer Community incident says the setting was injected into affected sessions and that a server-side fix was rolled out.

Those reports are incident evidence, not a permanent guarantee. If the same message recurs, verify current service state and the request you can actually observe.

Recover in the Codex App or Extension

1. Copy any unsent prompt or important task state.

2. Do not delete ~/.codex, clear chat history, rewrite config.toml, or reinstall merely because of this message.

3. Wait briefly and retry the same turn once. If it succeeds, treat the failure as transient.

4. If it fails again, check OpenAI service status and start a small, disposable task with the same model. This separates a route-wide failure from one damaged task.

5. If status is healthy and a fresh task fails, update to the current stable Codex release through the normal updater and capture the client version, model, timestamp, and request ID shown by the error before reporting it.

Do not repeatedly resend a tool-using turn. A prior attempt may already have completed some local or external work before the model response failed. Inspect the working tree and any external destination before retrying a mutation.

This differs from a capacity failure or quota exhaustion. If the message says the selected model is at capacity, use the capacity recovery decision tree. If usage changes unexpectedly, use the Codex usage-limit audit. A stream ending before completion is a separate response-stream recovery problem.

Fix a Custom GPT-5.6 or Later Request

OpenAI's current prompt caching guide assigns different controls to different model generations. GPT-5.6 and later use prompt_cache_options.ttl; the only documented TTL is 30m, which is also the default. Earlier models use prompt_cache_retention, with allowed values depending on the model.

For a GPT-5.6 or later request, remove this legacy field:

{
  "prompt_cache_retention": "24h"
}

If you need to state the current TTL explicitly, use the documented structure:

{
  "prompt_cache_options": {
    "ttl": "30m"
  }
}

Otherwise omit the lifetime control and use the model default. Do not silently translate 24h to 30m; that changes retention behavior and may change cost or data-handling assumptions. Review the model table and your retention requirements first.

Log the final outbound request after SDK and gateway transforms, with secrets and user content redacted. The configuration in your source file is not proof of what reached the API.

Verify the Recovery

A successful recovery should satisfy all of these checks:

• the request no longer returns the compatibility error;

• the selected model and cache field match the current documentation;

• a retried tool turn did not duplicate a write;

• no unrelated local configuration or task history was deleted; and

• the next ordinary turn completes without the field reappearing.

If a hosted Codex client still injects the setting after a service recovery, record a minimal reproduction instead of adding unsupported local workarounds. Include the client version, model, timestamp with timezone, whether a new task reproduces it, and whether the outbound request can be observed.

Check Current Reports With Aident Loadout

When the error may be an active incident, Aident Loadout can keep the check read-only and separate current evidence from local speculation. Install and authenticate the public CLI:

Follow https://aident.ai/SETUP.md

aident account auth status
aident vault vault --action status
aident capabilities search --targetEnv staging \
  --queries '["search current public reports for an exact Codex error"]'

Ask Codex to inspect the returned search Action, preflight the exact query, and execute only a read operation. Search the full error string, include the selected model and client, and compare timestamps. Do not grant a write acknowledgement or paste provider credentials into the prompt.

Use this reusable prompt:

Use Aident Loadout to search current public sources for the exact error prompt_cache_retention is not supported on this model. Inspect the live Action schema and preflight before execution. Keep the check read-only. Separate official documentation, official incident statements, and community reports. Return source URLs, timestamps, affected clients and models, confirmed fixes, and unresolved claims. Do not change my Codex configuration or retry any external write.

Set up Aident Loadout and verify the current incident before changing local state.

Sources

• OpenAI prompt caching guide

• OpenAI Developer Community incident report

• Current Codex community report and recovery observations

• OpenAI service status

• Aident Loadout setup

Refresh this guide when OpenAI changes the GPT-5.6 cache contract, the incident report receives a materially different root cause, or Codex publishes a client-specific recovery procedure.