spring-projects/spring-ai · warning

JSON validation failed: ${validationResponse}

Error message

JSON validation failed: ${validationResponse}

What it means

StructuredOutputValidationAdvisor validates LLM JSON output against the requested schema after the call. When validation fails on an attempt (and attempts remain), it logs a warning with the SchemaValidation result and augments the prompt with the validation error so the LLM can retry and produce corrected JSON. This is a mid-flight retry signal, not a terminal failure, unless attempts run out.

Source

Thrown at spring-ai-client-chat/src/main/java/org/springframework/ai/chat/client/advisor/StructuredOutputValidationAdvisor.java:157

			// We should not validate tool call requests, only the content of the final
			// response.
			if (chatResponse == null || !chatResponse.hasToolCalls()) {
				SchemaValidation validationResponse = validateOutputSchema(chatClientResponse,
						currentAttemptNumber - 1);

				isValidationSuccess = validationResponse.success();

				if (!isValidationSuccess) {

					// Add the validation error message to the next user message
					// to let the LLM fix its output.
					// Note: We could also consider adding the previous invalid output.
					// However, this might lead to confusion and more complex prompts.
					// Instead, we rely on the LLM to generate a new output based on the
					// validation error.
					if (logger.isWarnEnabled()) {
						logger.warn("JSON validation failed: " + validationResponse);
					}

					String validationErrorMessage = "Output JSON validation failed because of: "
							+ validationResponse.errorMessage();

					Prompt augmentedPrompt = chatClientRequest.prompt()
						.augmentUserMessage(userMessage -> userMessage.mutate()
							.text(userMessage.getText() + System.lineSeparator() + validationErrorMessage)
							.build());

					processedChatClientRequest = chatClientRequest.mutate().prompt(augmentedPrompt).build();
				}
				else if (logger.isDebugEnabled()) {
					logger.debug("JSON validation succeeded");
				}
			}
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Improve the format instructions / schema description in the prompt so the model produces conforming JSON
2. Use a model better at structured output or a provider's native JSON/structured-output mode
3. Increase the advisor's max attempts so the retry loop can converge
4. Parse the final validation error and, if it still fails, fall back to manual parsing/repair of the output

Example fix

// before
ChatClient.create(chatModel).prompt().user(question)
    .advisors(new StructuredOutputValidationAdvisor(1)) // no retries
    .call().entity(MyRecord.class);
// after
.advisors(new StructuredOutputValidationAdvisor(3)) // allow fix-up retries

// client-side schema check on model output before trusting it
ObjectMapper om = new ObjectMapper();
JsonNode node = om.readTree(outputText);
Set<ValidationMessage> errs = schema.validate(node);
if (!errs.isEmpty()) { /* augment prompt and retry */ }

try {
    MyRecord r = client.prompt().user(q)
        .advisors(new StructuredOutputValidationAdvisor(3))
        .call().entity(MyRecord.class);
} catch (IllegalStateException e) {
    // attempts exhausted; log e.getMessage() with validation detail
}

When it happens

Trigger: Using StructuredOutputValidationAdvisor (via ChatClient .entity(...) with a JSON schema) when the model's textual output fails schema/JSON validation — e.g. missing required fields, wrong types, or invalid JSON, often because the model ignored the format instructions.

Common situations: Small models producing non-conforming JSON; prompts that encourage prose around JSON; complex nested schemas the model struggles to satisfy on the first attempt.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to parse JSON schema
• Failed to parse JSON:
• JacksonException (wrapped IllegalStateException)
• ChatClientResponse is missing required json output for valid
• Error parsing JSON-RPC message:

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