{"record":{"id":"f8c95ca20f1f107a","repo":"can1357/oh-my-pi","slug":"openai-explicit-prompt-caching-is-unsupported-for","errorCode":null,"errorMessage":"OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; Azure Responses does not emit explicit cache controls.","messagePattern":"OpenAI explicit prompt caching is unsupported for (.+?)/(.+?); Azure Responses does not emit explicit cache controls\\.","errorType":"exception","errorClass":"AIError.ConfigurationError","httpStatus":null,"severity":"error","filePath":"packages/ai/src/providers/azure-openai-responses.ts","lineNumber":270,"sourceCode":"\t\t\toutput.duration = performance.now() - startTime;\n\t\t\tif (firstTokenTime) output.ttft = firstTokenTime - startTime;\n\t\t\tstream.push({ type: \"error\", reason: output.stopReason, error: output });\n\t\t\tstream.end();\n\t\t}\n\t})();\n\n\treturn stream;\n};\n\n/**\n * Retries transient Azure stream failures only before assistant output commits\n * the attempt. The unsupported explicit prompt-cache config is rejected\n * synchronously here — callers of the direct entrypoint get the immediate\n * `ConfigurationError` rather than a stream whose `.result()` rejects later.\n */\nexport const streamAzureOpenAIResponses: StreamFunction<\"azure-openai-responses\"> = (model, context, options) => {\n\tif (options?.promptCache?.mode === \"explicit\" && resolveCacheRetention(options.cacheRetention) !== \"none\") {\n\t\tthrow new AIError.ConfigurationError(\n\t\t\t`OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; Azure Responses does not emit explicit cache controls.`,\n\t\t);\n\t}\n\treturn withReplaySafeStreamRetry(model, context, options, streamAzureOpenAIResponsesOnce, {\n\t\tretryProviderErrors: true,\n\t\tmaxProviderErrorRetries: 1,\n\t});\n};\n\nfunction resolveAzureConfig(\n\tmodel: Model<\"azure-openai-responses\">,\n\toptions?: AzureOpenAIResponsesOptions,\n): { baseUrl: string; apiVersion: string } {\n\tconst apiVersion = options?.azureApiVersion || $env.AZURE_OPENAI_API_VERSION || DEFAULT_AZURE_API_VERSION;\n\n\tconst baseUrl = options?.azureBaseUrl?.trim() || $env.AZURE_OPENAI_BASE_URL?.trim() || undefined;\n\tconst resourceName = options?.azureResourceName || $env.AZURE_OPENAI_RESOURCE_NAME;\n","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/ai/src/providers/azure-openai-responses.ts#L252-L288","documentation":"The Azure OpenAI Responses provider does not support explicit prompt caching (client-emitted cache control markers). When a caller requests `promptCache.mode === \"explicit\"` with a non-none cache retention, the library rejects the request synchronously with a ConfigurationError so callers of the direct stream entrypoint fail fast instead of getting a stream that rejects later.","triggerScenarios":"Calling streamAzureOpenAIResponses (or getModel-based streaming against an azure-openai-responses model) with options.promptCache.mode set to \"explicit\" while resolveCacheRetention(options.cacheRetention) is not \"none\".","commonSituations":"Shared request-building code that enables explicit caching for OpenAI/Anthropic models is reused for Azure Responses models; a user flag like --prompt-cache explicit applied to all providers; migration of code from the OpenAI provider to the Azure Responses provider without removing cache options.","solutions":["Remove the explicit promptCache option (or set promptCache.mode to something other than \"explicit\") when targeting Azure OpenAI Responses models.","Set options.cacheRetention to \"none\" (or leave it undefined) so the guard resolves to \"none\" and passes.","Branch in your request-building code: only attach explicit cache controls for providers that support them (e.g. OpenAI, Anthropic), not azure-openai-responses.","Rely on Azure's implicit/automatic prompt caching, which requires no client-side cache controls."],"exampleFix":"// before\nstreamAzureOpenAIResponses(model, context, {\n  promptCache: { mode: \"explicit\" },\n  cacheRetention: \"24h\",\n});\n// after\nstreamAzureOpenAIResponses(model, context, {\n  // explicit caching unsupported on Azure Responses; use implicit caching\n  cacheRetention: \"none\",\n});","handlingStrategy":"validation","validationCode":"if (options?.promptCache?.mode === \"explicit\" && model.provider === \"azure-openai-responses\") {\n  throw new Error(\"Explicit prompt caching unsupported for Azure Responses; omit promptCache options.\");\n}","typeGuard":"null","tryCatchPattern":"try {\n  await streamAzureOpenAIResponses(model, ctx, options);\n} catch (err) {\n  if (err instanceof AIError.ConfigurationError && err.message.includes(\"explicit prompt caching\")) {\n    // retry without cache options\n  } else throw err;\n}","preventionTips":["Gate explicit caching options per provider capability, not globally.","Centralize request-option building so provider-specific constraints live in one place.","Test streaming calls with all option combinations your app emits."],"tags":["configuration","prompt-caching","azure-openai","unsupported-feature"],"backgroundTag":"unsupported-prompt-cache-mode","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}