When I upgraded a service from Spring Boot 3 to 4, the framework and web-layer changes got all the attention — but the part that actually cost me an afternoon was the repository layer. Spring Boot 4 pulls in the Spring Data 2025.1 generation (Spring Data JPA 4.0), and that carries three changes that don’t show up in a casual read of the release notes: an annotation-processor coordinate that was renamed out from under you, a complete rewrite of how derived queries are generated, and a much friendlier story for modelling value objects. None of these are loud failures. Two of them compile cleanly and then misbehave, which is the worst kind.
This guide walks the whole repository-layer migration beginner to advanced, on a real Spring Boot 4.1.0 project running Spring Data JPA 4.0, Hibernate 7.1, and Java 25. We start with how to confirm which Spring Data generation you’re actually on, then the hibernate-processor coordinate swap and the silent metamodel failure it causes, then the CriteriaQuery-to-JPQL rewrite of derived queries and its one real behavioural edge, then value objects — records as embeddables and as projections — and finally the removals that will fail your build outright. Every error message below is the real one, not a paraphrase.