spring-projects/spring-ai · info

The topK option is not supported by OpenAI chat models…

Error message

The topK option is not supported by OpenAI chat models. Ignoring.

What it means

verifyPromptChatOptions inspects the per-call Prompt options and warns that topK is not a parameter supported by the OpenAI chat completion API. The option is silently ignored — the request is still sent without topK. Spring AI throws/logs this to surface a portability issue: code written for models that use topK (e.g. Ollama) silently loses that setting when pointed at OpenAI.

Solutions

1. Remove the topK setting from the options used with OpenAI chat models
2. If temperature-like control is needed, use OpenAI-supported knobs such as temperature or topP instead
3. Use provider-specific OpenAiChatOptions when constructing the Prompt

Example fix

// before
OpenAiChatOptions options = OpenAiChatOptions.builder().topK(40).temperature(0.7).build();
// after
OpenAiChatOptions options = OpenAiChatOptions.builder().temperature(0.7).topP(0.9).build();

if (options != null && options.getTopK() != null) {
    // strip it before calling OpenAI
    options = OpenAiChatOptions.fromOptions(options).mutate().topK(null).build();
}

When it happens

Trigger: Passing a Prompt whose ChatOptions has a non-null topK to OpenAiChatModel.call(prompt) or stream(prompt) — typically via OpenAiChatOptions.builder().topK(n) or runtime options set for another provider.

Common situations: Swapping model implementations (e.g. from Ollama/Vertex to OpenAI) while reusing the same options object; copying sample code that sets topK; configuring topK via shared application options.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Both maxTokens and maxCompletionTokens are set. OpenAI API…
• Both maxTokens and maxCompletionTokens are set. OpenAI API…
• Conversion from JSON to
• Failed to parse JSON schema:
• Failed to parse toolChoice JSON:

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/73f23569bd021907. Report an issue: GitHub.

Appendix: source

Thrown at models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatModel.java:503

		try {
			return result.created();
		}
		catch (OpenAIInvalidDataException ex) {
			return 0L;
		}
	}

	private DefaultUsage getDefaultUsage(CompletionUsage usage) {
		Long cacheRead = usage.promptTokensDetails().flatMap(details -> details.cachedTokens()).orElse(null);
		return new DefaultUsage(Math.toIntExact(usage.promptTokens()), Math.toIntExact(usage.completionTokens()),
				Math.toIntExact(usage.totalTokens()), usage, cacheRead, null);
	}

	private void verifyPromptChatOptions(Prompt prompt) {
		var chatOptions = prompt.getOptions();

		if (chatOptions != null && chatOptions.getTopK() != null) {
			logger.warn("The topK option is not supported by OpenAI chat models. Ignoring.");
		}
	}

	/**
	 * Creates a chat completion request from the given prompt.
	 * @param prompt the prompt containing messages and options
	 * @param stream whether this is a streaming request
	 * @return the chat completion create parameters
	 */
	ChatCompletionCreateParams createRequest(Prompt prompt, boolean stream) {

		List<ChatCompletionMessageParam> chatCompletionMessageParams = prompt.getInstructions()
			.stream()
			.map(message -> {
				if (message.getMessageType() == MessageType.USER || message.getMessageType() == MessageType.SYSTEM) {
					// Handle simple text content for user and system messages
					ChatCompletionUserMessageParam.Builder builder = ChatCompletionUserMessageParam.builder();

View on GitHub (pinned to 98a7beda4f)