Most JPA entity trouble in a Spring Boot project comes from a short list of causes: a missing starter, a wrong identifier type, a query technique used beyond its limits, or a repository that does not match its interface. This guide takes each symptom in turn. For each one you get the likely causes, ordered from most to least probable, the fix, and a way to confirm it worked.
No version number is pinned here, because the reference pages used for this guide do not list one. Read the Spring Boot and Spring Data JPA versions from your own build file and check the matching reference documentation if behaviour differs.
Start from a baseline entity that works
Before you chase an error, compare your class with the smallest entity that works. It needs three things: the @Entity annotation on the class, an @Id field, and @GeneratedValue when the database should create the key.
You also need the JPA starter. It brings in Spring Data JPA and Hibernate. Add it to your pom.xml if it is not there.
Use the wrapper type Long for the identifier, not long. The reason matters later: Query by Example treats null as "not set", and a primitive can never be null.
The class below is complete. It uses the jakarta.persistence package, the same namespace as the EntityManager in the Spring Data JPA custom repository example.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
package com.example.demo;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
@Entity
public class Employee {
@Id
@GeneratedValue
private Long id;
private String name;
private String dept;
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getDept() { return dept; }
public void setDept(String dept) { this.dept = dept; }
}
package com.example.demo;
import org.springframework.data.jpa.repository.JpaRepository;
public interface EmployeeRepository extends JpaRepository<Employee, Long> {
}
Symptom: jakarta.validation.NoProviderFoundException at startup
You start the application, or use bean validation annotations on an entity, and the log shows jakarta.validation.NoProviderFoundException.
Likely causes, most probable first
- The validation starter is not on the classpath. The JPA starter does not replace it.
- You added the dependency to a different module than the one that runs the application.
- Your IDE has not reloaded the Maven model after you edited
pom.xml.
Fix
Add the validation starter next to the JPA starter. This supplies the validation provider that the error says is missing.
Then reload the Maven project in your IDE, or rebuild from the terminal.
Confirm it worked
Restart the application. The exception is gone from the startup log and the application context starts.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
mvn clean package
Symptom: Query by Example ignores your filter or returns the wrong rows
You build a probe entity, call findAll(Example), and get every row, or get no rows when you expect some.
Likely causes, most probable first
- A primitive identifier. Query by Example leaves out fields that are
null. Alongorintidentifier defaults to0, so0becomes part of the query. Change the field toLongorInteger. - A non-String field set on the probe. All types other than String match exactly. A default value such as
0orfalseis still a value. - Unexpected string matching. The default match for a String is exact. The matcher can also do case-insensitive, starts, ends, contains and regex matching. Pass an
ExampleMatcherthroughExample.of(probe, matcher). Check the Spring Data JPA reference for the exact matcher methods, because they are not listed here. - A field you did not mean to set. Constructors or field initialisers that assign defaults put those values in the query.
Fix
Use wrapper types for identifiers, set only the fields you want to filter on, and keep the probe otherwise empty.
With only name set, the query is equivalent to SELECT t from Employee t where t.name = 'Erika'.
Confirm it worked
Seed two employees with different names. Call countByName with one name. You get 1, not the total row count.
package com.example.demo;
import org.springframework.data.domain.Example;
import org.springframework.stereotype.Service;
@Service
public class EmployeeSearch {
private final EmployeeRepository repo;
public EmployeeSearch(EmployeeRepository repo) {
this.repo = repo;
}
public long countByName(String name) {
Employee probe = new Employee();
probe.setName(name);
return repo.count(Example.of(probe));
}
public Iterable<Employee> findByNameAndDept(String name, String dept) {
Employee probe = new Employee();
probe.setName(name);
probe.setDept(dept);
return repo.findAll(Example.of(probe));
}
}
Symptom: you cannot express the query with Query by Example
You need (firstName = ?0 and lastName = ?1) or seatNumber = ?2, or a comparison other than equality on a number, and Query by Example has no way to say it.
Likely causes, most probable first
- Nesting and grouping. Query by Example does not support them.
- Non-String comparisons. Types other than String are exact-match only, so ranges are not possible.
- A single probe cannot hold alternatives. The probe and its
ExampleMatchertogether describe one query.
Fix
Move that query to JpaSpecificationExecutor or to JPQL. Keep Query by Example for simple equality and string filters, where it needs no extra code.
The Spring Data JPA query methods page describes the other ways to define queries.
Confirm it worked
Run the new query with data that proves the grouping: one row that matches only the left side of the or, and one that matches only the right side. Both rows must come back.
Symptom: a custom repository does not compile or is not picked up
You add a custom interface and an implementation that uses EntityManager, and the build fails or the method is never reached.
Likely causes, most probable first
- Return types differ. An implementation that declares
List<SubjectCatRecord>cannot override an interface method that returnsList<SubjectGatRecord>. One letter apart is enough to break the build. Use one record type in both places. - Naming. The custom interface is
SubjectsRepoCustomand the class isSubjectsRepoCustomImpl. Keep the interface name plusImpl. - The main repository does not extend the custom interface. Add it to the
extendslist of your repository. - The wrong annotation or package. Inject the manager with
@jakarta.persistence.PersistenceContexton a field of typejakarta.persistence.EntityManager, and annotate the class with@Repository.
Fix
Align the types, the names and the extends list.
When the query takes user input, bind it as a parameter. Never build the SQL string by concatenation. The query API calls are not covered here, so check the Spring Data JPA reference for them.
Confirm it worked
The project compiles. Calling the repository method reaches your implementation, which you can check with a breakpoint.
Symptom: relationship mapping is wrong or associations load slowly
Relationship mapping covers one-to-many, many-to-many and similar associations. This guide does not give annotation details for them, so it does not list attribute names. Use the Spring Data JPA reference and the Jakarta Persistence specification for the exact annotations and attributes.
What you can check without them:
Likely causes, most probable first
- Association handling is the usual place performance problems start. Spring Data JPA guidance treats it as a key topic, so look at how and when related entities are loaded.
- Unclear ownership. Decide which side of the association holds the key before you write annotations on both sides.
- Missing identifiers on the related entity. Each entity needs
@Id, as in the baseline above.
Fix
Map one association at a time. After each one, load a sample row and look at the queries your application runs, using your own logging set-up.
Confirm it worked
The related data is present when you read it, and the number of queries stays small as the number of rows grows.
Symptom: a property placeholder in an entity annotation does not resolve
You try a Spring Boot property placeholder inside an entity annotation, for example in the schema attribute of @Table, and it does not work.
Likely causes, most probable first
- Annotation values are not resolved like Spring bean properties. A reported case shows the placeholder form failing in this exact place.
- The name is read literally. The persistence layer receives your placeholder text, not the property value.
Fix
This guide does not cover a tested solution. Check the Spring Boot and Spring Data JPA reference for the supported way to set schema or table naming, and keep the value as a plain string in the annotation until you find it.
Confirm it worked
The application starts and queries reach the intended schema and table.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| jakarta.validation.NoProviderFoundException on startup | The spring-boot-starter-validation dependency is missing. | Add spring-boot-starter-validation to pom.xml, reload Maven and restart. |
| findAll(Example) returns every row | The probe has no non-null fields, or all fields are null so none are used in the query. | Set at least one field on the probe. Confirm with count(Example). |
| Query by Example adds an unwanted id = 0 condition | The entity uses a primitive identifier such as long, which defaults to 0 instead of null. | Change the identifier to the wrapper type Long. |
| Cannot express an or with grouped conditions | Query by Example does not support nesting and grouping. | Use JpaSpecificationExecutor or JPQL. |
| Custom repository implementation fails to compile | The return type of the implementation differs from the interface, for example SubjectCatRecord against SubjectGatRecord. | Use the same record type in the interface and the implementation. |
Frequently asked questions
What is the minimum a Spring Boot JPA entity needs?
An @Entity class with an @Id field. Add @GeneratedValue when the database should create the key, and add spring-boot-starter-data-jpa to the project.
Why does Query by Example not filter on my id field?
Query by Example omits null fields. A primitive id defaults to 0, not null, so use the wrapper type Long.
Which dependency fixes jakarta.validation.NoProviderFoundException?
Add spring-boot-starter-validation to your dependencies.
Can Query by Example run queries with or and grouping?
No. Nesting and grouping are not supported. Use JpaSpecificationExecutor or JPQL.
Where do I find annotation details for relationship mapping?
Use the Spring Data JPA reference and the Jakarta Persistence specification. This guide does not list those annotation attributes.
References
From Grokem: https://www.grokem.com/programming/web-development/backend/spring-boot-jpa-entity-errors-causes-and-fixes-for-mapping-and-id-issues









