Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Boot fails on startup: HikariPool-1 exception during pool initialization

ErrorHikariPool-1 - Exception during pool initialization

Short answer

HikariCP opens one connection when the pool starts, and the startup fails when that connection fails. The message is a wrapper: the real reason is in the Caused by lines below it. Check the JDBC URL and database host first, then the driver class, then how long the pool may wait.

  • Applies to Spring Boot 3, HikariCP 5 and 6, MySQL 8.4, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Scroll to the last Caused by line of the stack trace. That line, not the Hikari line, names the problem.

    grep -n "Caused by" app.log | tail -5
  2. 2Match what you see, then jump to its fix

    1. 1The cause mentions the host, port or a refused or timed-out connectionThe JDBC URL is missing or points at the wrong placeFix
    2. 2The cause says the driver was not found or no suitable driverThe driver cannot be resolved from the URLFix
    3. 3It works on a second start, or in Docker only on the first runThe app starts before the database accepts connectionsFix

What does the error look like?

  • HikariPool-1 - Exception during pool initialization
  • Caused by: ... (the underlying driver exception)

Cause 1 of 3

The JDBC URL is missing or points at the wrong place

1Check

In Spring Boot you must set spring.datasource.url. Without it Boot tries to auto-configure an embedded database instead. Hikari throws a SQLException when no connection becomes available within connectionTimeout (30 seconds by default, minimum 250 ms).

grep -rn "datasource" src/main/resources/application*
nc -vz db-host 5432

2Fix

Set the URL, username and password for the database you really run.

spring.datasource.url=jdbc:postgresql://db-host:5432/app
spring.datasource.username=appuser
spring.datasource.password=${DB_PASSWORD}

3Verify

Restart the application; the pool starts without the exception.

mvn spring-boot:run

Confirmed by docs.spring.io

Did this fix it?

Cause 2 of 3

The driver cannot be resolved from the URL

1Check

HikariCP tries to resolve a driver through DriverManager from the jdbcUrl alone, and its docs say to set driverClassName only after an obvious driver-not-found error. Spring Boot deduces the driver from the URL for most databases.

mvn dependency:tree | grep -i "mysql\|postgresql"

2Fix

Add the driver for your database to the build. Set spring.datasource.driver-class-name only if Boot cannot deduce it.

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

3Verify

Restart and check the first Hikari log line.

mvn spring-boot:run

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The app starts before the database accepts connections

1Check

By default (initializationFailTimeout = 1) HikariCP tries to obtain and validate a connection and fails startup if it cannot. A positive value makes it keep trying for that many milliseconds; a negative value skips the initial attempt and starts the pool immediately.

docker compose ps

2Fix

Make the database ready first (a health check and depends_on condition). If you prefer to wait inside the app, give the pool a startup window.

spring.datasource.hikari.initialization-fail-timeout=60000

3Verify

Start both services together.

docker compose up

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep the datasource URL, user and password in environment variables per environment, not in the code.
  • Use a health check so the app container waits for the database.
  • Read the last Caused by line first; fix that, not the Hikari line.

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.