spring-projects/spring-ai · error · IllegalStateException

JacksonException (wrapped IllegalStateException)

Error message

JacksonException (wrapped IllegalStateException)

What it means

BeanOutputConverter.getJsonSchemaMap() parses the generated JSON Schema string with Jackson into a Map; if the schema string is not parseable, JacksonException is logged and rethrown as IllegalStateException. This means the internally produced JSON Schema is malformed or the jsonSchema field was set to invalid JSON.

Source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/converter/BeanOutputConverter.java:241

		return String.format(template, this.jsonSchema);
	}

	/**
	 * Provides the generated JSON schema for the target type.
	 * @return The generated JSON schema.
	 */
	@Override
	public String getJsonSchema() {
		return this.jsonSchema;
	}

	public Map<String, Object> getJsonSchemaMap() {
		try {
			return this.jsonMapper.readValue(this.jsonSchema, Map.class);
		}
		catch (JacksonException ex) {
			logger.error("Could not parse the JSON Schema to a Map object", ex);
			throw new IllegalStateException(ex);
		}
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Let BeanOutputConverter generate the schema from the target type instead of injecting a custom jsonSchema string.
2. Validate the target class's schema with getJsonSchema() and a JSON validator to find the malformed portion.
3. Upgrade Spring AI to a version with fixed schema generation for your types.
4. Wrap getJsonSchemaMap() in try-catch and fall back to parsing getJsonSchema() defensively.

Example fix

// before
new BeanOutputConverter<Record>(type, null, "not-json", ...).getJsonSchemaMap();
// after
BeanOutputConverter<Record> c = new BeanOutputConverter<>(type);
String schema = c.getJsonSchema(); // generated, guaranteed valid JSON

try { new ObjectMapper().readTree(converter.getJsonSchema()); } catch (Exception e) { /* schema invalid — regenerate or fix type */ }

try { return converter.getJsonSchemaMap(); } catch (IllegalStateException e) { logger.warn("JSON schema unparseable; using raw schema string", e); return Map.of(); }

When it happens

Trigger: Calling getJsonSchemaMap() on a BeanOutputConverter whose jsonSchema string was never generated, was overwritten with invalid JSON, or a target class whose generated schema fails Jackson parsing.

Common situations: Manually constructing/patching a BeanOutputConverter with a hand-written schema string; using exotic generic type parameters that break schema generation; older Spring AI versions where schema generation produced invalid JSON for some types.

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.

Related errors

• Failed to parse JSON:
• Cannot deserialize ThinkOption from token:
• Failed to parse JSON schema
• Conversion from JSON to %s failed
• JSON validation failed: ${validationResponse}

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