Spring Boot cannot create the HikariDataSource: no suitable driver class
Failed to instantiate [com.zaxxer.hikari.HikariDataSource]: Factory method 'dataSource' threw exception with message: Failed to determine a suitable driver classShort answer
Spring Boot builds the pool from spring.datasource.url and deduces the JDBC driver from it. This error means the url never reached the app, the driver jar is not on the classpath, or driver-class-name names a class that cannot be loaded. Print the effective settings, then fix whichever one is missing.
Fix it fast
1Find out which cause you have
Check what datasource settings the running app really received. In Docker, look at the container environment, not only the file in your repo.
docker compose exec app env | grep -i -E "datasource|SPRING" grep -rn "spring.datasource\|datasource:" src/main/resources/2Match what you see, then jump to its fix
- 1
The container has no SPRING_DATASOURCE_URL, or the file with the url is not packaged or not loaded for the active profilespring.datasource.url is not set in the running appFix - 2
The url is present and looks right, but the app has no driver dependency for that databaseThe JDBC driver is not on the classpathFix - 3
spring.datasource.driver-class-name is set explicitly, with a class name from an old tutorial or a different driver versiondriver-class-name names a class that cannot be loadedFix
- 1
What does the error look like?
Failed to instantiate [com.zaxxer.hikari.HikariDataSource]: Factory method 'dataSource' threw exception with message: Failed to determine a suitable driver class
Cause 1 of 3
spring.datasource.url is not set in the running app
1Check
Spring Boot expects the url. Without it, it tries to auto-configure an embedded database, and fails if none is on the classpath.
docker compose config | grep -i datasource
docker compose exec app env | grep -i SPRING_DATASOURCE2Fix
Set the url, username and password where the app can see them, for example as environment variables in the compose file.
services:
app:
environment:
SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/appdb
SPRING_DATASOURCE_USERNAME: app
SPRING_DATASOURCE_PASSWORD: change-me3Verify
Restart the service and read the log: the pool starts instead of throwing.
docker compose up -d --force-recreate app && docker compose logs --tail 50 appConfirmed by docs.spring.io
Cause 2 of 3
The JDBC driver is not on the classpath
1Check
Spring Boot can deduce the driver class from the url, but the class must be loadable. List the dependencies and look for the driver.
mvn dependency:tree | grep -i -E "postgresql|mysql|mariadb|sqlserver|ojdbc"2Fix
Add the driver for your database at runtime scope.
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>3Verify
Rebuild and start the app; the datasource pool is created.
mvn -q clean package && java -jar target/app.jarConfirmed by docs.spring.io
Cause 3 of 3
driver-class-name names a class that cannot be loaded
1Check
When you set the property, that exact class has to be loadable. Compare it with the driver jar you ship.
grep -rn "driver-class-name" src/main/resources/
unzip -l target/app.jar | grep -i driver2Fix
Remove the property so Spring Boot deduces the driver from the url, or set it to the class your driver version provides.
spring:
datasource:
url: "jdbc:mysql://db:3306/appdb"
username: "app"
password: "change-me"
# no driver-class-name: deduced from the url3Verify
Start the app and confirm the pool starts.
java -jar target/app.jarConfirmed by docs.spring.io
How do I stop it coming back?
- Keep database settings in one place per environment and print them (without the password) at startup in non-production.
- In compose, make the app wait for a healthy database so the failure shows the real connection error, not a startup race.
- Leave driver-class-name out unless you truly need it.
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
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
composer require laravel/horizon fails: ext-pcntl is missing
laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system
Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.
3 causes, each with a fixBack end
npm install fails inside a node:alpine Docker build
Docker Node Alpine Image Build Fails on node-gyp
The node alpine images ship almost nothing beyond Node.js, so a native module that node-gyp must compile has no Python, make or C++ compiler.
2 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
docker build stops at RUN composer install with exit code 1
Allowed memory size of ... bytes exhausted
Exit code 1 only says the RUN step failed.
4 causes, each with a fixBack end
A Docker build or container says npm: not found
npm: command not found
A container only has the programs its image holds.
3 causes, each with a fix