brettwooldridge/HikariCP · warning · SQLTransientException

The pool is currently suspended and configured to throw exce

Error message

The pool is currently suspended and configured to throw exceptions upon acquisition

What it means

SuspendResumeLock.acquire() normally blocks when the pool is suspended (all permits drained). If the system property com.zaxxer.hikari.throwIfSuspended=true, acquiring while suspended instead throws SQLTransientException immediately, letting callers fail fast instead of hanging during suspension.

Source

Thrown at src/main/java/com/zaxxer/hikari/util/SuspendResumeLock.java:69

    * Default constructor
    */
   public SuspendResumeLock()
   {
      this(true);
   }

   private SuspendResumeLock(final boolean createSemaphore)
   {
      acquisitionSemaphore = (createSemaphore ? new Semaphore(MAX_PERMITS, true) : null);
   }

   public void acquire() throws SQLException
   {
      if (acquisitionSemaphore.tryAcquire()) {
         return;
      }
      else if (Boolean.getBoolean("com.zaxxer.hikari.throwIfSuspended")) {
         throw new SQLTransientException("The pool is currently suspended and configured to throw exceptions upon acquisition");
      }

      acquisitionSemaphore.acquireUninterruptibly();
   }

   public void release()
   {
      acquisitionSemaphore.release();
   }

   public void suspend()
   {
      acquisitionSemaphore.acquireUninterruptibly(MAX_PERMITS);
   }

   public void resume()
   {
      acquisitionSemaphore.release(MAX_PERMITS);

View on GitHub (pinned to a4d93f4f85)

Solutions

1. If fast failure is desired: catch SQLTransientException and retry after a backoff until resumePool() completes
2. Schedule work to stop before suspendPool() (quiesce) and resume after maintenance
3. If blocking is acceptable, remove -Dcom.zaxxer.hikari.throwIfSuspended so acquisition waits for resume
4. Bound retries with a deadline shorter than the expected maintenance window and degrade gracefully

Example fix

// before
Connection c = ds.getConnection(); // throws SQLTransientException while suspended

// after
SQLException last = null;
for (int i = 0; i < 30; i++) {
   try { return ds.getConnection(); }
   catch (SQLTransientException e) { last = e; Thread.sleep(1000); }
}
throw last;

// before borrowing, check pool state via MXBean if suspension is possible
if (hikariPoolMXBean != null && suspended) { /* wait or degrade */ }

try { conn = ds.getConnection(); }
catch (SQLTransientException e) {
    if (e.getMessage().contains("currently suspended")) { backoffAndRetry(); }
    else throw e;
}

When it happens

Trigger: Pool suspended via suspendPool() (allowPoolSuspension=true) during DB maintenance/failover, and getConnection() called while suspended with -Dcom.zaxxer.hikari.throwIfSuspended=true set; ops tooling that suspends while traffic still arrives.

Common situations: Planned maintenance windows, blue/green failover automation that suspends pools, health-check probes hitting a suspended pool.

Related errors

• ${poolName} - is not suspendable
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• idleTimeout cannot be negative
• maxPoolSize cannot be less than 1
• minimumIdle cannot be negative

AI-assisted analysis of brettwooldridge/HikariCP@a4d93f4f85 (2026-08-14). Data as JSON: /api/errors/c793a0773f013726. Report an issue: GitHub.