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}; Azure Responses does not emit explicit cache controls.

What it means

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.

Source

Thrown at packages/ai/src/providers/azure-openai-responses.ts:270

			output.duration = performance.now() - startTime;
			if (firstTokenTime) output.ttft = firstTokenTime - startTime;
			stream.push({ type: "error", reason: output.stopReason, error: output });
			stream.end();
		}
	})();

	return stream;
};

/**
 * Retries transient Azure stream failures only before assistant output commits
 * the attempt. The unsupported explicit prompt-cache config is rejected
 * synchronously here — callers of the direct entrypoint get the immediate
 * `ConfigurationError` rather than a stream whose `.result()` rejects later.
 */
export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"> = (model, context, options) => {
	if (options?.promptCache?.mode === "explicit" && resolveCacheRetention(options.cacheRetention) !== "none") {
		throw new AIError.ConfigurationError(
			`OpenAI explicit prompt caching is unsupported for ${model.provider}/${model.id}; Azure Responses does not emit explicit cache controls.`,
		);
	}
	return withReplaySafeStreamRetry(model, context, options, streamAzureOpenAIResponsesOnce, {
		retryProviderErrors: true,
		maxProviderErrorRetries: 1,
	});
};

function resolveAzureConfig(
	model: Model<"azure-openai-responses">,
	options?: AzureOpenAIResponsesOptions,
): { baseUrl: string; apiVersion: string } {
	const apiVersion = options?.azureApiVersion || $env.AZURE_OPENAI_API_VERSION || DEFAULT_AZURE_API_VERSION;

	const baseUrl = options?.azureBaseUrl?.trim() || $env.AZURE_OPENAI_BASE_URL?.trim() || undefined;
	const resourceName = options?.azureResourceName || $env.AZURE_OPENAI_RESOURCE_NAME;

View on GitHub (pinned to 9690622007)

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.

Example fix

// before
streamAzureOpenAIResponses(model, context, {
  promptCache: { mode: "explicit" },
  cacheRetention: "24h",
});
// after
streamAzureOpenAIResponses(model, context, {
  // explicit caching unsupported on Azure Responses; use implicit caching
  cacheRetention: "none",
});

Defensive patterns

Strategy: validation

Validate before calling

if (options?.promptCache?.mode === "explicit" && model.provider === "azure-openai-responses") {
  throw new Error("Explicit prompt caching unsupported for Azure Responses; omit promptCache options.");
}

Type guard

null

Try / catch

try {
  await streamAzureOpenAIResponses(model, ctx, options);
} catch (err) {
  if (err instanceof AIError.ConfigurationError && err.message.includes("explicit prompt caching")) {
    // retry without cache options
  } else throw err;
}

Prevention

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.

When it happens

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

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

Related errors

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