Spring Boot with MyBatis: sqlSessionFactory or sqlSessionTemplate are required
Property 'sqlSessionFactory' or 'sqlSessionTemplate' are requiredShort 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.
Fix it fast
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/java2Match what you see, then jump to its fix
- 1
The dependency list has mybatis-spring but no mybatis-spring-boot-starterOnly the base mybatis-spring library is used, not the Boot starterFix - 2
The starter is on the classpath but auto-configuration never runsThe starter does not match the Spring Boot versionFix - 3
The project defines more than one DataSource bean and its own configuration class for MyBatisTwo DataSources, and the mapper has no factory to useFix
- 1
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:runConfirmed by mybatis.org
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 -DforceStdout2Fix
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 -DskipTestsConfirmed by mybatis.org
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/java2Fix
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:runConfirmed by raw.githubusercontent.com
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
Back end
Hibernate: PersistentObjectException, detached entity passed to persist
jakarta.persistence.EntityExistsException
persist() is for new objects.
2 causes, each with a fixBack end
Apache HttpClient 5 has no setSSLSocketFactory on HttpClients.custom()
HttpClients.custom().setSSLSocketFactory() method not found
In Apache HttpClient 5 the TLS setup no longer sits on the client builder.
2 causes, each with a fixBack end
A scanner flags jackson-databind: how to upgrade it in Gradle
jackson-databind vulnerability reported by a dependency scanner
Find where the old jackson-databind comes from, then raise it.
3 causes, each with a fixBack end
Spring Boot cannot bind spring.datasource.password with Jasypt ENC() values
Failed to bind properties under 'spring.datasource.password' to java.lang.String
The binding error means Jasypt could not turn the ENC(...) value back into plain text.
3 causes, each with a fixBack end
Gradle cannot resolve spring-boot-gradle-plugin after a Spring Boot 3 upgrade
Plugin [id: 'org.springframework.boot', version: '3.0.1'] was not found in any of the following sources
Spring Boot 3 needs Java 17 or newer and a recent Gradle, and its Gradle plugin is published on the Gradle Plugin Portal.
3 causes, each with a fixBack end
Spring Boot global CORS configuration has no effect, but @CrossOrigin works
The preflight OPTIONS request has no Access-Control headers, and a controller annotated with @CrossOrigin on the same app answers correctly
Spring checks CORS only after it maps a request to a handler, and only against a configuration that matches that request.
6 causes, each with a fix