HikariCP “Connection Is Not Available, Request Timed Out”: How to Find the Real Cause

The error message tells you the pool ran out of connections. It does not tell you why. Before you change a setting, you need to know whether the pool is leaking connections, holding them too long, deadlocking on itself, failing to create new ones, or just too small.

Raising maximumPoolSize or connectionTimeout is the most common suggestion, and it is only the right fix for the last cause. This guide shows how to collect the evidence that tells the five causes apart. That evidence includes pool metrics, leak detection traces, thread dumps, and database session state, plus a map of the code paths that acquire and release connections.

What does “Connection is not available, request timed out” mean?

A HikariCP pool keeps a fixed maximum number of physical database connections (maximumPoolSize, default 10). When application code calls getConnection(), HikariCP hands over an idle connection. If none is idle and the pool is already at its maximum, the calling thread waits. If the wait exceeds connectionTimeout (default 30,000 ms), the call fails.

java.sql.SQLTransientConnectionException: HikariPool-1 -
  Connection is not available, request timed out after 30000ms (total=10, active=10, idle=0, waiting=4)
    at com.zaxxer.hikari.pool.HikariPool.createTimeoutException(HikariPool.java)
    at com.zaxxer.hikari.pool.HikariPool.getConnection(HikariPool.java)
    at com.zaxxer.hikari.HikariDataSource.getConnection(HikariDataSource.java)

Recent HikariCP versions append the pool statistics to the message. Those four numbers are the first piece of evidence, and most people skip them.

Five causes, one error message

Developer questions about this error on Stack Overflow keep circling the same confusion. The pool is exhausted. Is it a leak, a long running query, or a pool that is simply too small? The honest answer is that the error cannot tell you. The evidence around it can.

1. Connection creation failure

The pool is not full, yet threads time out. HikariCP is trying to open new physical connections and failing or taking too long. Common reasons are the database hitting max_connections (often because several services or replicas share it), network or DNS problems, TLS handshakes that stall, or credentials that were rotated. The stats show total below the maximum, and the exception usually carries the underlying cause.

2. Connection leak

A code path borrows a connection and never returns it. Each leak permanently removes one connection from the pool, so the pool degrades step by step until it is empty. The signature is active climbing over hours or days and not coming back down when traffic falls. Restarting the service “fixes” it until the leak catches up again.

3. Long hold: slow queries, long transactions, and remote calls

Nothing is leaked, but each borrower keeps its connection for much longer than expected. A query that used to take 20 ms now takes 2 seconds because of a missing index, lock contention, or a larger table. A transaction wraps an HTTP call, a message publish, or file processing. The connection is returned eventually, so active drops when load drops. Under load it is pinned.

4. Pool deadlock from nested acquisition

A thread that already holds a connection asks the pool for a second one. Common culprits are Propagation.REQUIRES_NEW, a second DataSource.getConnection() inside a transaction, or a callback that opens its own session. With a pool of 10 and 10 concurrent requests that each hold one connection and wait for another, no thread can finish. They all wait until connectionTimeout.

5. Undersized pool

Every borrower behaves correctly and returns its connection quickly, but demand simply exceeds supply. This is the only cause where increasing maximumPoolSize is the fix, and it can only be confirmed after ruling out the other four.

Collect the evidence first

Each cause leaves different fingerprints. Gather these five sources before changing anything, ideally during or right after an incident.

Evidence 1: Pool metrics over time

A single snapshot cannot distinguish a leak from a traffic spike. You need active, idle, pending, and connection usage time as a time series. If you use Micrometer (Spring Boot does this automatically with Actuator), HikariCP publishes:

• hikaricp.connections.active, .idle, .pending, .max
• hikaricp.connections.usage: how long connections are held between borrow and return. This is the most useful metric here.
• hikaricp.connections.acquire: how long threads wait to get one
• hikaricp.connections.timeout: count of timeouts

Without a metrics registry, turn on DEBUG logging for com.zaxxer.hikari. The housekeeper thread logs pool stats periodically (every 30 seconds by default), which is enough to see the trend:

HikariPool-1 - Before cleanup stats (total=10, active=4, idle=6, waiting=0)
HikariPool-1 - Before cleanup stats (total=10, active=7, idle=3, waiting=0)
HikariPool-1 - Before cleanup stats (total=10, active=10, idle=0, waiting=2)
HikariPool-1 - Before cleanup stats (total=10, active=10, idle=0, waiting=9)

Evidence 2: Leak detection stack traces

HikariCP can tell you who borrowed a connection that has been out too long. Leak detection is off by default. Enable it with a threshold above your longest legitimate hold time (the minimum is 2,000 ms):

# Warn when a connection is held longer than 20 s, with the borrower's stack trace
spring.datasource.hikari.leak-detection-threshold=20000

# Periodic pool stats in the logs
logging.level.com.zaxxer.hikari=DEBUG

# Expose HikariPoolMXBean over JMX (active, idle, threads awaiting connection)
spring.datasource.hikari.register-mbeans=true

HikariConfig config = new HikariConfig();
config.setJdbcUrl(url);
config.setMaximumPoolSize(10);
config.setLeakDetectionThreshold(20_000); // ms; 0 = disabled (default)
config.setRegisterMbeans(true);

When the threshold is crossed, HikariCP logs the stack trace captured at the moment the connection was borrowed. That tells you exactly which code path took it:

Connection leak detection triggered for org.postgresql.jdbc.PgConnection@6b1d4f
  on thread http-nio-8080-exec-7, stack trace follows
java.lang.Exception: Apparent connection leak detected
    at com.zaxxer.hikari.HikariDataSource.getConnection(HikariDataSource.java)
    at com.example.report.ReportDao.export(ReportDao.java:42)
    at com.example.report.ReportService.nightlyExport(ReportService.java:88)

Now watch for what happens next. If the same connection is later returned, HikariCP logs a follow-up:

Previously reported leaked connection org.postgresql.jdbc.PgConnection@6b1d4f
  on thread http-nio-8080-exec-7 was returned to the pool (unleaked)

Evidence 3: Thread dumps

A thread dump taken while threads are waiting separates the two populations you care about: threads waiting for a connection, and threads holding one.

# Take two or three dumps ~10 s apart during the incident
jcmd <pid> Thread.print > threads-1.txt

# How many threads are waiting on the pool?
grep -c "HikariPool.getConnection" threads-1.txt

Waiting threads are parked inside the pool:

"http-nio-8080-exec-12" TIMED_WAITING (parking)
    at java.util.concurrent.locks.LockSupport.parkNanos
    at java.util.concurrent.SynchronousQueue.poll
    at com.zaxxer.hikari.util.ConcurrentBag.borrow
    at com.zaxxer.hikari.pool.HikariPool.getConnection
    at org.springframework.orm.jpa.JpaTransactionManager.doBegin

The holders are more interesting. Look at what threads inside your data access code are doing:

• Blocked in a socket read from the JDBC driver: waiting on the database. Suspect slow queries or locks.
• Inside an HTTP client, message producer, or Thread.sleep while also inside a transaction: a long hold caused by application code.
• In HikariPool.getConnection while already inside a transactional method: nested acquisition. If most waiters look like this, it is a pool deadlock.
• No thread appears to own the missing connections: they were leaked by code that has already moved on.

Evidence 4: The database’s view of the sessions

The database sees every one of the pool’s connections and knows what each is doing. In PostgreSQL:

SELECT pid, state, wait_event_type, wait_event,
       now() - xact_start  AS xact_age,
       now() - query_start AS query_age,
       left(query, 80)     AS last_query
FROM   pg_stat_activity
WHERE  datname = current_database()
  AND  backend_type = 'client backend'
ORDER BY xact_start NULLS LAST;

For MySQL, use SHOW FULL PROCESSLIST and information_schema.innodb_trx for the same picture. Setting the JDBC ApplicationName property makes the pool’s sessions easy to filter.

Evidence 5: The code paths themselves

The first four sources tell you what kind of problem you have. Only the code tells you where it is and how many other places share the same pattern. That gets its own section below.

Leak vs long running query vs undersized pool: how to tell them apart

This is the question most developers get stuck on. The pool looks the same in all three cases at the moment of the timeout. The difference shows up over time, and in where the connection time is spent.

The sizing arithmetic

The number of connections a service needs on average follows Little’s Law: throughput × average hold time. That is why a hold time problem and a capacity problem look identical from the outside.

The HikariCP project’s own pool sizing guidance argues for smaller pools than most teams expect. The database can only execute so many queries in parallel, and extra connections add contention rather than throughput. It also gives the minimum size that avoids pool deadlock when each thread needs several connections: Tn × (Cm − 1) + 1, where Tn is the maximum number of threads and Cm the maximum connections a single thread holds at once.

Map the code paths that acquire and release connections

Runtime evidence narrows the cause. It rarely hands you the complete list of code that has the problem. A leak detection trace shows the one path that tripped the threshold today, not the three other methods written the same way. To fix the class of problem rather than the instance, inventory the code paths that touch the pool:

1. Acquisition points. Every DataSource.getConnection(), @Transactional boundary, TransactionTemplate, EntityManager or Session opened manually, and repository method that returns a Stream<T> or cursor.
2. What happens while it is held. SQL only, or also HTTP calls, message publishing, file I/O, retries with backoff, sleep, or waiting on other threads?
3. Release on every path. Is close() guaranteed through try-with-resources or a framework template, including exception and early return paths?
4. Nested acquisition. Can a thread holding a connection request another through REQUIRES_NEW, a second data source call, or an event listener that opens its own transaction?
5. Blast radius. Which endpoints, jobs, and consumers share this pool, and what fails for them when it starves?

Here are the two patterns behind most real incidents, and what the fix looks like.

Leak: close() skipped on the exception path

public List<Row> export() throws SQLException {
    Connection conn = dataSource.getConnection();
    PreparedStatement ps = conn.prepareStatement(EXPORT_SQL);
    ResultSet rs = ps.executeQuery();
    List<Row> rows = toRows(rs);   // throws on a bad row: conn is never closed
    conn.close();
    return rows;
}

public List<Row> export() throws SQLException {
    try (Connection conn = dataSource.getConnection();
         PreparedStatement ps = conn.prepareStatement(EXPORT_SQL);
         ResultSet rs = ps.executeQuery()) {
        return toRows(rs);          // closed even if toRows throws
    }
}

The same pattern appears in less obvious forms. Examples include a Spring Data repository method returning Stream<T> that the caller never closes, DataSourceUtils.getConnection() without a matching releaseConnection(), and a connection passed to another thread or stored in a field.

Long hold: a remote call inside a transaction

@Transactional
public void placeOrder(Order order) {
    orderRepository.save(order);        // connection bound at transaction start
    paymentClient.charge(order);        // 3 s HTTP call: connection held, database idle
    order.markPaid();
}

public void placeOrder(Order order) {
    Long id = tx.execute(s -> orderRepository.save(order.pending()).getId());
    PaymentResult result = paymentClient.charge(order);   // no connection held
    tx.executeWithoutResult(s -> orderRepository.markPaid(id, result));
}

Splitting the transaction changes the consistency model. The order can now exist in a pending state if the payment call fails, so it needs a status and a retry or reconciliation path. That trade-off is exactly why this should be a reviewed design change, not a pool setting.

Fixes, matched to the cause

Evidence to require before suggesting a fix

Pool timeouts get “fixed” by configuration changes that ship quickly, pass review easily, and hide the real problem until the next traffic peak. Whether the fix comes from a teammate, a Stack Overflow answer, or an AI coding assistant, ask for the evidence that matches it:

This is the same discipline we apply to any change that affects shared production resources. The diff alone is not the evidence. The evidence is how the changed code acquires, holds, and releases what it shares, and what else depends on it. For the broader practice, see How to Assess the Blast Radius of a Code Change and Pre Merge Reliability Analysis.

How Tomosu helps

Tomosu analyzes the standing codebase and each change for this kind of production reliability risk. For connection pool exhaustion, the useful output is not another “increase your pool size” suggestion. It is the map from the previous section, with evidence attached:

• The code paths that acquire and release connections: transactional boundaries, manual getConnection() calls, returned streams, and whether each path releases on every branch.
• Risky holds: remote calls, retries, and slow work inside transactions, and nested acquisition that can deadlock the pool.
• Blast radius: which endpoints and jobs share the pool, so a finding in a nightly export is weighed differently from one on the checkout path.
• The evidence needed before a fix: what to check in metrics, leak traces, thread dumps, and the database to confirm the cause before a configuration change is approved.

These signals roll up into the Production Reliability Index, so a pull request that adds an HTTP call inside a @Transactional method is flagged before merge, not after the next peak.

Scan your repository with Tomosu →

Key takeaways

• “Connection is not available, request timed out” means a thread waited longer than connectionTimeout. It is a symptom, not a cause.
• Read the pool stats and the chained cause in the exception first. total below the maximum points to creation failure.
• Leak detection reports apparent leaks. A later “unleaked” message means a long hold, not a leak.
• Connection usage time, not query time alone, separates long holds from an undersized pool.
• Map every code path that acquires and releases connections. The leak trace shows one instance; the map shows the pattern.
• Increase maximumPoolSize only after the evidence rules out leaks, long holds, deadlock, and creation failure.

Frequently asked questions

A pool timeout is the last step of a longer story: a code path that acquired a connection and did not give it back in time. Tomosu maps those paths before they reach production. Assess your repository →