The Wire · Showcase
SPRING-AI HARDENS MCP EXCEPTION HANDLING, FIXES BUILDER STATE LEAKS
By RepoJournal · Filed · About Spring
Spring AI aligned exception handling across tool decorators and plugged a critical shared mutable state bug in chat options builders that could corrupt cloned instances.
The biggest move: @McpTool callbacks now mirror @Tool's exception contract [1], routing RuntimeExceptions to the model as error results while hard-failing on checked exceptions, Errors, and McpError instances. On the client side, McpError from remote MCP servers now re-throws directly instead of wrapping in ToolExecutionException, giving you finer control over failure modes. This surfaces as a breaking change if you're catching ToolExecutionException for MCP-specific errors.
Meanwhile, Spring AI squashed a nasty shared mutable state bug [2] where ChatOptions builder clone() methods copied collection fields by reference instead of defensively copying them. That meant mutating a cloned builder corrupted its source. The fix mirrors defensive copying already happening in combineWith() and aligns the base ChatOptions contract across all implementations.
Builder API improvements landed too: OpenAiEmbeddingModel and OpenAiImageModel [3] now use the builder pattern for consistency. Spring Tools bumped actions/checkout to 7.0.0 [4] and actions/setup-java to 5.4.0 [5], both routine security and dependency updates. Spring Data JPA [6] expanded MEMBER OF support to map KEY() and VALUE() expressions, and tightened validation to reject missing explicitly named queries [7] instead of falling back to misleading parameter errors.
Action items
- → Review MCP tool exception handling if you're catching ToolExecutionException for MCP callbacks spring-projects/spring-ai [plan]
- → Upgrade Spring AI to pick up the ChatOptions clone() fix before heavy builder usage spring-projects/spring-ai [plan]
- → Test Spring Data JPA queries with explicitly named @Query annotations to catch validation changes spring-projects/spring-data-jpa [monitor]
References
- [1] Align @McpTool exception handling with @Tool contract ↗ spring-projects/spring-ai
- [2] Fix shared mutable state in chat options builder `clone()` ↗ spring-projects/spring-ai
- [3] Use builder pattern for `OpenAiEmbeddingModel` and `OpenAiImageModel` ↗ spring-projects/spring-ai
- [4] Bump actions/checkout from 6.0.3 to 7.0.0 ↗ spring-projects/spring-tools
- [5] Bump actions/setup-java from 5.2.0 to 5.4.0 ↗ spring-projects/spring-tools
- [6] Allow map key and value expressions in collection membership. spring-projects/spring-data-jpa
- [7] Reject missing explicitly named queries. spring-projects/spring-data-jpa
FAQ
- What changed in Spring on July 3, 2026?
- Spring AI aligned exception handling across tool decorators and plugged a critical shared mutable state bug in chat options builders that could corrupt cloned instances.
- What should Spring teams do about it?
- Review MCP tool exception handling if you're catching ToolExecutionException for MCP callbacks • Upgrade Spring AI to pick up the ChatOptions clone() fix before heavy builder usage • Test Spring Data JPA queries with explicitly named @Query annotations to catch validation changes
- Which Spring repositories shipped on July 3, 2026?
- spring-projects/spring-ai, spring-projects/spring-tools, spring-projects/spring-data-jpa