can1357/oh-my-pi · error · AIError.ConfigurationError

OpenAI explicit prompt caching is unsupported for ${model.pr

Error message

OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; enable compat.supportsPromptCacheBreakpoints only for a compatible endpoint.

What it means

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.

Source

Thrown at packages/ai/src/stream.ts:1930

		model.api === "azure-openai-responses" ||
		(model.api === "openrouter" && $env.PI_OPENROUTER_RESPONSES !== "0")
	);
}

function assertExplicitOpenAIResponsesPromptCacheSupport<TApi extends Api>(
	model: Model<TApi>,
	options?: StreamOptions,
): void {
	if (
		model.transport === "pi-native" ||
		resolveCacheRetention(options?.cacheRetention) === "none" ||
		options?.promptCache?.mode !== "explicit" ||
		!isOpenAIResponsesPromptCacheSurface(model) ||
		supportsExplicitOpenAIResponsesPromptCache(model.compat)
	) {
		return;
	}
	throw new AIError.ConfigurationError(
		`OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; enable compat.supportsPromptCacheBreakpoints only for a compatible endpoint.`,
	);
}

function mapOptionsForApi<TApi extends Api>(
	model: Model<TApi>,
	rawOptions?: SimpleStreamOptions,
	apiKey?: string,
): OptionsForApi<TApi> {
	const options = normalizeMandatoryReasoningOptions(model, rawOptions);
	const simpleProviderOptions = getProviderDefinition(model.provider)?.mapSimpleOptions?.(options ?? {});
	const base = {
		temperature: options?.temperature,
		topP: options?.topP,
		topK: options?.topK,
		minP: options?.minP,
		presencePenalty: options?.presencePenalty,
		repetitionPenalty: options?.repetitionPenalty,

View on GitHub (pinned to 9690622007)

Solutions

1. Remove promptCache mode "explicit" for that model (use default/implicit caching) or scope the option to supported models.
2. Enable compat.supportsPromptCacheBreakpoints in the model's compat entry only if the endpoint truly supports cache breakpoints (KDL rule for catalog-managed models).
3. Point the request at the native OpenAI Responses endpoint instead of a compatible proxy.
4. Upgrade the catalog so the model carries the correct compat flags.

Example fix

// before
await stream(model, ctx, { promptCache: { mode: "explicit" } }); // model lacks compat flag
// after
await stream(model, ctx); // implicit caching, or gate the option:
if (supportsExplicitOpenAIResponsesPromptCache(model.compat)) {
  await stream(model, ctx, { promptCache: { mode: "explicit" } });
}

if (requestOptions?.promptCache?.mode === "explicit" &&
    !(model.compat?.supportsPromptCacheBreakpoints && isOpenAIResponsesPromptCacheSurface(model))) {
  // fall back to implicit caching or skip the option
  const { promptCache, ...rest } = requestOptions;
  requestOptions = rest;
}

function supportsExplicitCache(model: Model): boolean {
  return isOpenAIResponsesPromptCacheSurface(model) && supportsExplicitOpenAIResponsesPromptCache(model.compat);
}

try {
  await stream(model, context, requestOptions);
} catch (err) {
  if (err instanceof AIError.ConfigurationError && err.message.includes("explicit prompt caching is unsupported")) {
    logger.warn("Explicit prompt cache unsupported for model; retrying with implicit caching");
    const { promptCache, ...rest } = requestOptions;
    return stream(model, context, rest);
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• OpenAI explicit prompt caching is unsupported for ${model.pr
• An OpenAI API credential is required for file uploads
• No model configured
• Azure OpenAI base URL is required. Set AZURE_OPENAI_BASE_URL
• Model ${model.id} does not support V2 streaming compaction

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/2cc31791da131922. Report an issue: GitHub.