spring-projects/spring-ai · error · IllegalArgumentException

Failed to parse JSON schema

Error message

Failed to parse JSON schema

What it means

StructuredOutputValidationAdvisor's constructor parses the supplied JSON schema string with Jackson (jsonMapper.readTree) and then validates it against JSON Schema draft 2020-12 via SchemaRegistry. If the string is not parseable JSON, it throws IllegalArgumentException('Failed to parse JSON schema', e) with the underlying parse error as cause.

Source

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

		Assert.notNull(outputJsonSchema, "outputJsonSchema must not be null");
		Assert.isTrue(advisorOrder > BaseAdvisor.HIGHEST_PRECEDENCE && advisorOrder < BaseAdvisor.LOWEST_PRECEDENCE,
				"advisorOrder must be between HIGHEST_PRECEDENCE and LOWEST_PRECEDENCE");
		Assert.isTrue(maxRepeatAttempts >= 0, "repeatAttempts must be greater than or equal to 0");
		Assert.notNull(jsonMapper, "jsonMapper must not be null");

		this.advisorOrder = advisorOrder;
		this.jsonMapper = jsonMapper;

		if (logger.isDebugEnabled()) {
			logger.debug("Generated JSON Schema:\n" + outputJsonSchema);
		}

		JsonNode schemaNode;
		try {
			schemaNode = jsonMapper.readTree(outputJsonSchema);
		}
		catch (Exception e) {
			throw new IllegalArgumentException("Failed to parse JSON schema", e);
		}

		SchemaRegistry schemaRegistry = SchemaRegistry.withDefaultDialect(SpecificationVersion.DRAFT_2020_12);
		this.jsonSchema = schemaRegistry.getSchema(schemaNode);

		this.maxRepeatAttempts = maxRepeatAttempts;
	}

	@SuppressWarnings("null")
	@Override
	public String getName() {
		return "Structured Output Validation Advisor";
	}

	@Override
	public int getOrder() {
		return this.advisorOrder;
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Validate the schema string with a JSON parser before constructing the advisor (read e.getCause() for the exact syntax error position).
2. Generate the schema with JsonSchemaGenerator.generateForType(Class) instead of hand-writing it.
3. If loading from a file/classpath, confirm the file content is valid JSON (e.g. with a linter or ObjectMapper.readTree in a startup check).
4. Fix quoting/escaping issues when the schema comes from env vars or config.

Example fix

// before
new StructuredOutputValidationAdvisor("{\"type\":\"object\",}", 3); // trailing comma
// after
String schema = "{\"type\":\"object\"}";
new ObjectMapper().readTree(schema); // fail fast with a clear error
new StructuredOutputValidationAdvisor(schema, 3);

String schema = /* your schema string */;
try { new ObjectMapper().readTree(schema); } catch (Exception e) { throw new IllegalStateException("invalid JSON schema: " + e.getMessage()); }

try { new StructuredOutputValidationAdvisor(schema, 3); } catch (IllegalArgumentException e) { if (e.getMessage().equals("Failed to parse JSON schema")) { log.error("schema syntax error", e.getCause()); } throw e; }

When it happens

Trigger: Constructing StructuredOutputValidationAdvisor with an outputJsonSchema string that is malformed JSON: truncated string, comments/trailing commas, a Java string template placeholder left unsubstituted, or an empty/whitespace value that passed earlier checks.

Common situations: Hand-written schemas with trailing commas, schema loaded from a properties/env var with quoting issues, reading the schema file with wrong encoding so the content is garbled, or generating the schema dynamically and injecting invalid text.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• JSON validation failed: ${validationResponse}
• Failed to parse JSON:
• Failed to parse JSON schema:
• Only outputType or outputJsonSchema can be set, not both.
• Either outputType or outputJsonSchema must be set.

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