Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Spring Boot with MyBatis: sqlSessionFactory or sqlSessionTemplate are required

ErrorProperty 'sqlSessionFactory' or 'sqlSessionTemplate' are required

Short answer

A mapper bean was created, but no SqlSessionFactory or SqlSessionTemplate was given to it. In Spring Boot the MyBatis starter creates both from your DataSource. So the starter is missing, the version does not match your Boot version, or you have two DataSources and auto-configuration steps aside.

  • Applies to Spring Boot 3.5, mybatis-spring-boot-starter 3.0
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the MyBatis libraries on the classpath and note the Spring Boot version. Then search for your own SqlSessionFactory bean.

    ./mvnw dependency:tree | grep -i mybatis
    grep -rn "SqlSessionFactory" src/main/java
  2. 2Match what you see, then jump to its fix

    1. 1The dependency list has mybatis-spring but no mybatis-spring-boot-starterOnly the base mybatis-spring library is used, not the Boot starterFix
    2. 2The starter is on the classpath but auto-configuration never runsThe starter does not match the Spring Boot versionFix
    3. 3The project defines more than one DataSource bean and its own configuration class for MyBatisTwo DataSources, and the mapper has no factory to useFix

What does the error look like?

  • Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required

Cause 1 of 3

Only the base mybatis-spring library is used, not the Boot starter

1Check

MapperFactoryBean needs a SqlSessionFactory or a SqlSessionTemplate. The starter is what auto-detects the DataSource and registers both.

./mvnw dependency:tree | grep -iE 'mybatis-spring|starter'

2Fix

Use the starter that matches your Spring Boot version and remove the separate mybatis and mybatis-spring entries.

<dependency>
  <groupId>org.mybatis.spring.boot</groupId>
  <artifactId>mybatis-spring-boot-starter</artifactId>
  <version>3.0.x</version>
</dependency>

3Verify

The application starts, and a mapper call reaches the database.

./mvnw spring-boot:run

Confirmed by mybatis.org

Did this fix it?

Cause 2 of 3

The starter does not match the Spring Boot version

1Check

The compatibility table pairs starter 3.0 with Spring Boot 3.2 to 3.5, and starter 4.0 with Spring Boot 4.0 and later.

./mvnw help:evaluate -Dexpression=project.parent.version -q -DforceStdout

2Fix

Change the starter version to the one listed for your Boot version.

<!-- Spring Boot 3.2 to 3.5 -->
<version>3.0.x</version>

3Verify

Rebuild and start; the error is gone.

./mvnw clean package -DskipTests

Confirmed by mybatis.org

Did this fix it?

Cause 3 of 3

Two DataSources, and the mapper has no factory to use

1Check

The starter documentation says manual configuration, for example with multiple DataSources, is not covered by auto-configuration. You define each SqlSessionFactory yourself and tell each mapper scan which one to use.

grep -rn "DataSource\|MapperScan" src/main/java

2Fix

Create one SqlSessionFactory per DataSource and point each @MapperScan at its own factory.

@Configuration
@MapperScan(basePackages = "com.example.orders",
            sqlSessionFactoryRef = "ordersSessionFactory")
class OrdersMyBatisConfig {
    @Bean
    SqlSessionFactory ordersSessionFactory(@Qualifier("ordersDataSource") DataSource ds) throws Exception {
        SqlSessionFactoryBean bean = new SqlSessionFactoryBean();
        bean.setDataSource(ds);
        return bean.getObject();
    }
}

3Verify

Every mapper package starts without the error.

./mvnw spring-boot:run

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Take the starter version from the compatibility table whenever you upgrade Spring Boot.
  • Name each SqlSessionFactory and keep one mapper package per DataSource.
  • Do not mix hand-written MyBatis beans with the starter unless you mean to replace its defaults.

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.