{"record":{"id":"2cc31791da131922","repo":"can1357/oh-my-pi","slug":"openai-explicit-prompt-caching-is-unsupported-for-2cc317","errorCode":null,"errorMessage":"OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; enable compat.supportsPromptCacheBreakpoints only for a compatible endpoint.","messagePattern":"OpenAI explicit prompt caching is unsupported for (.+?)/(.+?); enable compat\\.supportsPromptCacheBreakpoints only for a compatible endpoint\\.","errorType":"exception","errorClass":"AIError.ConfigurationError","httpStatus":null,"severity":"error","filePath":"packages/ai/src/stream.ts","lineNumber":1930,"sourceCode":"\t\tmodel.api === \"azure-openai-responses\" ||\n\t\t(model.api === \"openrouter\" && $env.PI_OPENROUTER_RESPONSES !== \"0\")\n\t);\n}\n\nfunction assertExplicitOpenAIResponsesPromptCacheSupport<TApi extends Api>(\n\tmodel: Model<TApi>,\n\toptions?: StreamOptions,\n): void {\n\tif (\n\t\tmodel.transport === \"pi-native\" ||\n\t\tresolveCacheRetention(options?.cacheRetention) === \"none\" ||\n\t\toptions?.promptCache?.mode !== \"explicit\" ||\n\t\t!isOpenAIResponsesPromptCacheSurface(model) ||\n\t\tsupportsExplicitOpenAIResponsesPromptCache(model.compat)\n\t) {\n\t\treturn;\n\t}\n\tthrow new AIError.ConfigurationError(\n\t\t`OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; enable compat.supportsPromptCacheBreakpoints only for a compatible endpoint.`,\n\t);\n}\n\nfunction mapOptionsForApi<TApi extends Api>(\n\tmodel: Model<TApi>,\n\trawOptions?: SimpleStreamOptions,\n\tapiKey?: string,\n): OptionsForApi<TApi> {\n\tconst options = normalizeMandatoryReasoningOptions(model, rawOptions);\n\tconst simpleProviderOptions = getProviderDefinition(model.provider)?.mapSimpleOptions?.(options ?? {});\n\tconst base = {\n\t\ttemperature: options?.temperature,\n\t\ttopP: options?.topP,\n\t\ttopK: options?.topK,\n\t\tminP: options?.minP,\n\t\tpresencePenalty: options?.presencePenalty,\n\t\trepetitionPenalty: options?.repetitionPenalty,","sourceCodeStart":1912,"sourceCodeEnd":1948,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/ai/src/stream.ts#L1912-L1948","documentation":"Explicit prompt caching (mode \"explicit\") for OpenAI Responses models is only supported on endpoints whose compat declares supportsPromptCacheBreakpoints. When a model requests explicit caching on a surface that cannot accept cache breakpoints, the library throws AIError.ConfigurationError naming the provider/model id — a deliberate misconfiguration guard, since silently dropping explicit breakpoints would change cost/caching behavior.","triggerScenarios":"Setting requestOptions.promptCache.mode to \"explicit\" (or mapping options that do) while the model's compat.supportsPromptCacheBreakpoints is falsy or the model is not an OpenAI Responses prompt-cache surface.","commonSituations":"Enabling explicit caching globally for all OpenAI models including ones routed to non-Responses endpoints; using a proxy/compatible endpoint that lacks breakpoint support; catalog entry missing the compat flag after a provider change.","solutions":["Remove promptCache mode \"explicit\" for that model (use default/implicit caching) or scope the option to supported models.","Enable compat.supportsPromptCacheBreakpoints in the model's compat entry only if the endpoint truly supports cache breakpoints (KDL rule for catalog-managed models).","Point the request at the native OpenAI Responses endpoint instead of a compatible proxy.","Upgrade the catalog so the model carries the correct compat flags."],"exampleFix":"// before\nawait stream(model, ctx, { promptCache: { mode: \"explicit\" } }); // model lacks compat flag\n// after\nawait stream(model, ctx); // implicit caching, or gate the option:\nif (supportsExplicitOpenAIResponsesPromptCache(model.compat)) {\n  await stream(model, ctx, { promptCache: { mode: \"explicit\" } });\n}","handlingStrategy":"validation","validationCode":"if (requestOptions?.promptCache?.mode === \"explicit\" &&\n    !(model.compat?.supportsPromptCacheBreakpoints && isOpenAIResponsesPromptCacheSurface(model))) {\n  // fall back to implicit caching or skip the option\n  const { promptCache, ...rest } = requestOptions;\n  requestOptions = rest;\n}","typeGuard":"function supportsExplicitCache(model: Model): boolean {\n  return isOpenAIResponsesPromptCacheSurface(model) && supportsExplicitOpenAIResponsesPromptCache(model.compat);\n}","tryCatchPattern":"try {\n  await stream(model, context, requestOptions);\n} catch (err) {\n  if (err instanceof AIError.ConfigurationError && err.message.includes(\"explicit prompt caching is unsupported\")) {\n    logger.warn(\"Explicit prompt cache unsupported for model; retrying with implicit caching\");\n    const { promptCache, ...rest } = requestOptions;\n    return stream(model, context, rest);\n  }\n  throw err;\n}","preventionTips":["Gate explicit promptCache options on model.compat.supportsPromptCacheBreakpoints.","Don't enable explicit caching globally for all OpenAI models.","Manage the compat flag via catalog KDL rules instead of ad-hoc patches."],"tags":["configuration","prompt-caching","openai","responses-api"],"backgroundTag":"unsupported-prompt-cache-config","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}