Introduction

Java HikariCP connection pool is exhausted when connections are not returned to the pool. This guide provides step-by-step diagnosis and resolution with specific commands and code examples.

Symptoms

Typical symptoms and error messages when this issue occurs:

bash
java.lang.Error: Unexpected error occurred
	at com.example.Application.main(Application.java:42)
Caused by: internal error

Observable indicators: - Application logs show errors or exceptions - JVM crashes or becomes unresponsive - Related services may fail or timeout

Common Causes

  1. 1.The issue is typically caused by:
  2. 2.Incorrect configuration parameters
  3. 3.Missing or incompatible dependencies
  4. 4.Resource exhaustion or timeout settings

Step-by-Step Fix

Step 1: Check Current State

bash
SHOW STATUS LIKE "Threads_connected";

Step 2: Identify Root Cause

bash
SELECT * FROM pg_stat_activity;

Step 3: Apply Primary Fix

```java // HikariCP configuration HikariConfig config = new HikariConfig(); config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb"); config.setUsername("user"); config.setPassword("password"); config.setMaximumPoolSize(20); config.setMinimumIdle(5); config.setConnectionTimeout(30000); config.setIdleTimeout(600000); config.setMaxLifetime(1800000);

HikariDataSource ds = new HikariDataSource(config); ```

Apply this configuration and restart the application.

Step 4: Apply Alternative Fix (If Needed)

java
# application.properties
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.idle-timeout=600000
spring.datasource.hikari.max-lifetime=1800000
spring.datasource.hikari.leak-detection-threshold=60000

Test the fix under normal and peak load conditions to verify stability.

Step 5: Verify the Fix

After applying the fix, verify with:

bash
java -jar application.jar --debug

Expected output should show successful operation without errors.

Common Pitfalls

  • Not reading error messages carefully
  • Applying fixes without understanding root cause
  • Skipping verification after changes

Best Practices

  • Read official documentation first
  • Test in isolated environment
  • Document changes for team visibility
  • Java OutOfMemoryError
  • Java StackOverflowError
  • Java ClassNotFoundException