Spring Boot discovers JPA entities from its auto-configuration packages, normally the package containing your @SpringBootApplication class and its subpackages. Put the application class above your entity packages when possible; for entities outside that tree, configure @EntityScan. Changing scanBasePackages alone does not change entity discovery.
How Spring Boot finds entities by default
Spring Boot determines the location of @Entity definitions by scanning its auto-configuration packages. In a conventional project, the package containing the main @SpringBootApplication or @EnableAutoConfiguration class is the root, and packages beneath it are included.
For example, if the application class is in com.example, entity classes in com.example.customer are within that package tree. A class in a sibling package such as com.shared.domain is not. Keeping the application class in a parent package of the domain model is usually the simplest arrangement.
The default entity model includes classes annotated with @Entity, @Embeddable, and @MappedSuperclass. In this auto-configured setup, a persistence.xml file is generally unnecessary.
#1 Best Overall
How to scan entities in another package or module
Add @EntityScan to configuration when the entities are outside the default package tree. A marker class makes the package boundary type-safe and avoids a package-name string that can become stale after a refactor:
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
@EntityScan(basePackageClasses = Customer.class)
public class Application {
}Here, Customer.class is a class in the package containing the entity model. You can provide more than one marker class when the entities occupy multiple packages.
Alternatively, basePackages accepts package names, and value is its alias. If no package attribute is supplied, scanning starts from the package containing the configuration class annotated with @EntityScan.
This is common in multi-module projects: the application module and domain module may have unrelated package roots. Explicitly identify the domain package for entity discovery rather than assuming that including another module as a dependency also expands the scan boundary.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why scanBasePackages does not find JPA entities
scanBasePackages and scanBasePackageClasses on @SpringBootApplication configure component scanning. They do not affect @Entity discovery or Spring Data repository scanning. A service bean appearing after a component-scan change is therefore not evidence that entities or repositories in that package are also configured.
Configure each concern independently when it lies outside the defaults:
Rank #4
- Use
@EntityScanto specify packages containing entity classes. - Use
@EnableJpaRepositoriesto specify packages containing Spring Data JPA repositories. - Use component-scan settings for application components such as services and configuration classes.
Which EntityScan import to use
The annotation’s package differs between Spring Boot 3.x and Boot 4.0. Check the import when upgrading rather than copying an example written for another major version.
| Spring Boot version | EntityScan import |
|---|---|
| 3.x | org.springframework.boot.autoconfigure.domain.EntityScan |
| 4.0 | org.springframework.boot.persistence.autoconfigure.EntityScan |
The annotation serves the same purpose in both versions: defining entity-scan packages. The package change is the version-specific detail that commonly causes an import error during an upgrade.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Best Value
How to limit scanning for a test or bounded model
If a persistence unit should include only part of a large model, Spring Boot supports a ManagedClassNameFilter bean to filter managed class names. For example, the documented pattern accepts fully qualified names beginning with com.example.app.customer.. This can keep a focused test or bounded context from including every entity in the application.
When using a filter, check that its matching rule is against fully qualified class names and that the intended entity packages satisfy it. A filter that excludes a required entity can produce a missing-entity failure even when the broader package boundary is correct.
Quick Recap
Troubleshoot an entity that is not found
- Check the entity type. Confirm the class has the intended
@Entity,@Embeddable, or@MappedSuperclassannotation. - Check the default root. Locate the package of the main
@SpringBootApplicationor@EnableAutoConfigurationclass and determine whether the entity’s package is beneath it. - Set the entity boundary if needed. For an entity in a sibling package or another module, add
@EntityScan(basePackageClasses = YourEntity.class)using a marker in that package. - Configure repositories separately. If repository interfaces are also outside the defaults, set their package with
@EnableJpaRepositories. - Review component-scan changes. If the only recent change was to
scanBasePackages, add the entity and repository configuration appropriate to their packages; component scanning does not cover those concerns. - Verify the Boot major version. For compilation or import errors, use the
EntityScanpackage documented for your Boot version. - Inspect test filters. If using
ManagedClassNameFilter, verify the filter matches the fully qualified names of the classes the persistence unit needs.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
