Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Boot stops with 'Unable to build Hibernate SessionFactory'

Errorjakarta.persistence.PersistenceException: [PersistenceUnit: default] Unable to build Hibernate SessionFactory

Short answer

This message only says that JPA could not start. The reason is the last 'Caused by' line. After a Spring Boot or Hibernate upgrade it is usually a missing datasource URL, a JDBC driver that is not on the classpath, or old javax.persistence imports and dependencies that no longer match the jakarta packages Boot 3 uses.

  • Applies to Spring Boot 3.4, Hibernate 6.6, MySQL Connector/J, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the last 'Caused by' line. It is the cause, and the other lines are wrappers. Then check which of the three below it matches.

    grep -n 'Caused by' app.log | tail -n 3
    ./mvnw dependency:tree | grep -E 'mysql|postgresql|hibernate|jakarta.persistence|javax.persistence'
  2. 2Match what you see, then jump to its fix

    1. 1The root cause is a datasource or driver error, and no spring.datasource.url is set in the active profileNo datasource URL, so Boot falls back to an embedded databaseFix
    2. 2The cause mentions that the driver class cannot be loaded, or no driver matches the URLThe JDBC driver is missing, or it is an old artifact or class nameFix
    3. 3ClassNotFoundException or NoSuchMethodError for javax.persistence or jakarta.persistence classes, often right after an upgradejavax.persistence code or libraries on a jakarta-based BootFix

What does the error look like?

  • jakarta.persistence.PersistenceException: [PersistenceUnit: default] Unable to build Hibernate SessionFactory
  • Could not open JPA EntityManager for transaction
  • Unable to build Hibernate SessionFactory

Cause 1 of 3

No datasource URL, so Boot falls back to an embedded database

1Check

Spring Boot expects spring.datasource.url. Without it, Boot tries to auto-configure an embedded database, and that fails if none is on the classpath.

grep -rn 'spring.datasource' src/main/resources/ config/ 2>/dev/null

2Fix

Set the URL, user name and password, and let Boot deduce the driver from the URL.

spring.datasource.url=jdbc:mysql://localhost:3306/appdb
spring.datasource.username=app_user
spring.datasource.password=change-me

3Verify

Start the app and watch for the Hibernate initialisation lines.

./mvnw spring-boot:run

Confirmed by docs.spring.io

Did this fix it?

Cause 2 of 3

The JDBC driver is missing, or it is an old artifact or class name

1Check

Boot deduces the driver class from the URL, but the class has to be loadable, so the driver dependency must be present. Boot 3 changed the MySQL driver coordinates from mysql:mysql-connector-java to com.mysql:mysql-connector-j.

./mvnw dependency:tree | grep -i 'mysql'

2Fix

Depend on the current driver and remove any old driver-class-name property that names a class that no longer loads.

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

3Verify

Rebuild; the dependency tree now lists mysql-connector-j.

./mvnw dependency:tree | grep mysql-connector-j

Confirmed by github.com

Did this fix it?

Cause 3 of 3

javax.persistence code or libraries on a jakarta-based Boot

1Check

Spring Boot 3 uses Jakarta EE 10 and the jakarta packages instead of javax, with Hibernate 6. A project or a third-party library that still imports javax.persistence will not work with it.

grep -rln 'javax.persistence' src/main/java
./mvnw dependency:tree | grep -i 'javax.persistence'

2Fix

Change the imports to jakarta.persistence and replace or upgrade any library that still brings the javax version.

// before
import javax.persistence.Entity;
// after
import jakarta.persistence.Entity;

3Verify

Rebuild and start; no javax.persistence appears in the dependency tree.

./mvnw clean package -DskipTests

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Read the migration guide before a major Spring Boot upgrade and run the app after each step.
  • Keep database settings in one profile file and test it with the database client.
  • Add a startup test that loads the application context, so a JPA failure shows up in CI.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.