Query rewrite result is null/empty. Returning the input…

Error message

Query rewrite result is null/empty. Returning the input query unchanged.

What it means

RewriteQueryTransformer asks a ChatModel (via a prompt template) to rewrite the user query for a target search system. When the model returns a null or blank string instead of usable text, the transformer logs this warning and returns the original query unchanged rather than corrupting the retrieval pipeline with empty input. It is a graceful-degradation path, not a hard failure.

Solutions

Check the model's raw response outside the transformer — if empty, inspect provider logs/content-filter flags and adjust the prompt to demand a rewritten query with no commentary.
Use a stronger model (e.g. OpenAiChatOptions with a more capable model) or increase maxTokens for the rewrite call.
Ensure the prompt template in RewriteQueryTransformer.defaultPromptTemplate or your custom one instructs the model to always output a query.
If unchanged queries are acceptable, keep the default behavior — the input query is returned safely and retrieval continues.

Example fix

// before: default model returning empty rewrites
QueryTransformer transformer = RewriteQueryTransformer.builder()
    .chatClientBuilder(weakModelClientBuilder)
    .build();
// after: capable model + explicit instruction
QueryTransformer transformer = RewriteQueryTransformer.builder()
    .chatClientBuilder(strongModelClientBuilder)
    .promptTemplate(new PromptTemplate("Rewrite the following query for {target}. Output ONLY the rewritten query:\n{query}"))
    .build();

Defensive patterns

Strategy: validation

Validate before calling

if (query != null && StringUtils.hasText(query.text())) {
    // safe to pass to transformer; result falls back to input if rewrite is empty
}

Prevention

Use a model known to comply with rewrite prompts and test its empty-response rate.
Set adequate maxTokens for the rewrite call.
Monitor provider content-filter metrics for your prompts.
Treat the returned original query as a signal to log and audit rewrite quality.

When it happens

Trigger: Calling transform(Query) on a RewriteQueryTransformer whose underlying ChatModel call returns null content or whitespace-only text — e.g. the model refuses, hits a content filter, returns an empty completion, or the prompt template fails to elicit a rewrite.

Common situations: Using a small/weak model that produces empty responses; aggressive content filtering on the provider (e.g. safety filters on Azure OpenAI); low maxTokens truncating output; the rewrite prompt confusing the model so it answers with nothing; provider outages returning empty bodies.

Understand the failure class

Background: "empty response", "returned no data", "empty embeddings": what HTTP 200-with-empty-body errors mean across libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at spring-ai-rag/src/main/java/org/springframework/ai/rag/preretrieval/query/transformation/RewriteQueryTransformer.java:90

	}

	@Override
	public Query transform(Query query) {
		Assert.notNull(query, "query cannot be null");

		if (logger.isDebugEnabled()) {
			logger.debug("Rewriting query to optimize for querying a " + this.targetSearchSystem + ".");
		}

		var rewrittenQueryText = this.chatClient.prompt()
			.user(user -> user.text(this.promptTemplate.getTemplate())
				.param("target", this.targetSearchSystem)
				.param("query", query.text()))
			.call()
			.content();

		if (!StringUtils.hasText(rewrittenQueryText)) {
			logger.warn("Query rewrite result is null/empty. Returning the input query unchanged.");
			return query;
		}

		return query.mutate().text(rewrittenQueryText).build();
	}

	public static Builder builder() {
		return new Builder();
	}

	public static final class Builder {

		private ChatClient.@Nullable Builder chatClientBuilder;

		private @Nullable PromptTemplate promptTemplate;

		private @Nullable String targetSearchSystem;

View on GitHub (pinned to 98a7beda4f)