spring-projects/spring-ai · error · IllegalArgumentException

Either outputType or outputJsonSchema must be set.

Error message

Either outputType or outputJsonSchema must be set.

What it means

StructuredOutputValidationAdvisor.Builder.build() requires an output specification: neither outputType nor outputJsonSchema was set, so build() throws IllegalArgumentException('Either outputType or outputJsonSchema must be set.'). Without one, the advisor cannot know what schema to validate model output against.

Source

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

		public Builder jsonMapper(JsonMapper jsonMapper) {
			this.jsonMapper = jsonMapper;
			return this;
		}

		/**
		 * Builds the StructuredOutputValidationAdvisor.
		 * @return a new StructuredOutputValidationAdvisor instance
		 * @throws IllegalArgumentException if neither outputType nor outputJsonSchema is
		 * set, or if both are set
		 */
		public StructuredOutputValidationAdvisor build() {

			if (StringUtils.hasText(this.outputJsonSchema) && this.outputType != null) {
				throw new IllegalArgumentException("Only outputType or outputJsonSchema can be set, not both.");
			}

			if (!StringUtils.hasText(this.outputJsonSchema) && this.outputType == null) {
				throw new IllegalArgumentException("Either outputType or outputJsonSchema must be set.");
			}

			if (this.outputType != null) {
				this.outputJsonSchema = JsonSchemaGenerator.generateForType(this.outputType);
			}

			return new StructuredOutputValidationAdvisor(this.advisorOrder,
					Objects.requireNonNull(this.outputJsonSchema), this.maxRepeatAttempts, this.jsonMapper);
		}

	}

	private record SchemaValidation(boolean success, String errorMessage) {

		private static SchemaValidation passed() {
			return new SchemaValidation(true, "");
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Call .outputType(YourResultType.class) to generate the schema from a Java type.
2. Or call .outputJsonSchema(validSchemaString) with an explicit JSON Schema.
3. Check that conditional code paths that set the output spec actually run before build().

Example fix

// before
StructuredOutputValidationAdvisor.builder().build();
// after
StructuredOutputValidationAdvisor.builder()
    .outputType(MyRecord.class)
    .build();

StructuredOutputValidationAdvisor.Builder b = StructuredOutputValidationAdvisor.builder();
if (resultType != null) b.outputType(resultType); else if (schema != null) b.outputJsonSchema(schema);
else throw new IllegalStateException("advisor needs outputType or outputJsonSchema");

try { advisorBuilder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Either outputType or outputJsonSchema")) { /* set the output spec */ } throw e; }

When it happens

Trigger: Calling StructuredOutputValidationAdvisor.builder().build() (or advisor() on a chain) without first calling outputType(...) or outputJsonSchema(...).

Common situations: Forgotten configuration when wiring the advisor into the advisor chain, refactoring that removed outputType but didn't add outputJsonSchema, or building the advisor conditionally where the branch setting the schema never executed.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Only outputType or outputJsonSchema can be set, not both.
• argumentType is required
• httpClientBuilderCustomizers cannot be combined with a pre-b
• httpClientBuilderCustomizers cannot be combined with a pre-b
• Failed to parse JSON schema:

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