spring-projects/spring-ai · error · RuntimeException

Failed to parse JSON Schema

Error message

Failed to parse JSON Schema

What it means

augmentToolInputSchema(String, ...) parses the tool's JSON Schema string into a Jackson ObjectNode, injects an augmented property, and serializes it back. Any exception during parse, mutation, or serialization is rethrown as a RuntimeException with this message. Note the message says 'parse' but the catch covers the whole method body, including serialization.

Source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/tool/augment/ToolInputSchemaAugmenter.java:130

					if (schemaObjectNode.has("required")) {
						requiredArray = (ArrayNode) schemaObjectNode.get("required");
					}
					else {
						requiredArray = JacksonUtils.getDefaultJsonMapper().createArrayNode();
						schemaObjectNode.set("required", requiredArray);
					}
					requiredArray.add(argument.name());

				}
			}

			return JacksonUtils.getDefaultJsonMapper()
				.writerWithDefaultPrettyPrinter()
				.writeValueAsString(schemaObjectNode);

		}
		catch (Exception e) {
			throw new RuntimeException("Failed to parse JSON Schema", e);
		}
	}

	/**
	 * Represents an extended argument type with additional metadata such as description
	 * and required status.
	 */
	public record AugmentedArgumentType(String name, Type type, String description, boolean required) {
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Validate the schema string parses as JSON (e.g. JacksonUtils.getDefaultJsonMapper().readTree(schema)) before augmenting.
2. Generate the base schema programmatically (e.g. from the tool's record via JsonSchemaGenerator) rather than hand-writing it.
3. Read the wrapped cause to identify whether the failure is in parsing or in writeValueAsString.

Example fix

// before
String augmented = ToolInputSchemaAugmenter.augmentToolInputSchema("{type: object}", "x", String.class, "d", true); // invalid JSON
// after
String schema = """{"type":"object","properties":{}}""";
String augmented = ToolInputSchemaAugmenter.augmentToolInputSchema(schema, "x", String.class, "d", true);

new com.fasterxml.jackson.databind.ObjectMapper().readTree(schemaString); // throws if the schema is not valid JSON

try { augmented = ToolInputSchemaAugmenter.augmentToolInputSchema(schema, prop, type, desc, req); } catch (RuntimeException e) { throw new IllegalArgumentException("Tool input schema is not valid JSON: " + e.getMessage(), e); }

When it happens

Trigger: Passing a malformed/non-JSON string as the tool input schema; passing empty or null schema text; a schema that cannot round-trip through the default Jackson mapper.

Common situations: Hand-written JSON Schema strings with trailing commas or comments; schemas obtained from another library's non-standard serialization; building schema strings by string concatenation instead of via Jackson.

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

• Error parsing JSON-RPC message:
• Failed to parse JSON:
• Failed to parse JSON:
• Failed to parse JSON schema:
• Failed to parse JSON schema

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