Maaz Zindani

Loading the index…

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

Spring Boot cannot create the HikariDataSource: no suitable driver class

ErrorFailed to instantiate [com.zaxxer.hikari.HikariDataSource]: Factory method 'dataSource' threw exception with message: Failed to determine a suitable driver class

Short 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.

  • Applies to Spring Boot 3.5, Spring Boot 4.0, HikariCP 6, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The url is present and looks right, but the app has no driver dependency for that databaseThe JDBC driver is not on the classpathFix
    3. 3spring.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

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_DATASOURCE

2Fix

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-me

3Verify

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 app

Confirmed by docs.spring.io

Did this fix it?

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.jar

Confirmed by docs.spring.io

Did this fix it?

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 driver

2Fix

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 url

3Verify

Start the app and confirm the pool starts.

java -jar target/app.jar

Confirmed by docs.spring.io

Did this fix it?

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

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 fix

Back 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 fix

Next step

Want this handled for good?

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