brettwooldridge/HikariCP · error · IllegalArgumentException

idleTimeout cannot be negative

Error message

idleTimeout cannot be negative

What it means

HikariCP validates that idleTimeout is not negative. idleTimeout controls how long an unused pooled connection is kept before being retired; a negative duration is meaningless, so setIdleTimeout(long) throws IllegalArgumentException immediately. Note this check only covers negativity: other invalid ranges (e.g. < 10s with minIdle < maxPoolSize) are auto-corrected with a warning later during validate(), not thrown.

Source

Thrown at src/main/java/com/zaxxer/hikari/HikariConfig.java:214

      }
      else {
         this.connectionTimeout = connectionTimeoutMs;
      }
   }

   /** {@inheritDoc} */
   @Override
   public long getIdleTimeout()
   {
      return idleTimeout;
   }

   /** {@inheritDoc} */
   @Override
   public void setIdleTimeout(long idleTimeoutMs)
   {
      if (idleTimeoutMs < 0) {
         throw new IllegalArgumentException("idleTimeout cannot be negative");
      }
      this.idleTimeout = idleTimeoutMs;
   }

   /** {@inheritDoc} */
   @Override
   public long getLeakDetectionThreshold()
   {
      return leakDetectionThreshold;
   }

   /** {@inheritDoc} */
   @Override
   public void setLeakDetectionThreshold(long leakDetectionThresholdMs)
   {
      this.leakDetectionThreshold = leakDetectionThresholdMs;
   }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Use 0 to disable idle timeout entirely (connections are never retired for idleness)
2. Otherwise pass a positive value, ideally >= 10000 (10s) so validate() does not reset it to the default
3. Search the config source for where -1 comes from (env var, placeholder, profile overlay) and correct it there

Example fix

// before
config.setIdleTimeout(-1); // IllegalArgumentException

// after
config.setIdleTimeout(0); // disable idle timeout
// or
config.setIdleTimeout(600000); // 10 minutes

if (idleTimeoutMs < 0) idleTimeoutMs = 0; // 0 = disabled
config.setIdleTimeout(idleTimeoutMs);

When it happens

Trigger: Calling config.setIdleTimeout(n) with n < 0, or setting idleTimeout=-1 / a negative value in properties, Spring Boot yml, or a programmatic config builder. Happens when -1 is used to mean 'infinite' (a convention from other libraries) rather than HikariCP's convention of 0.

Common situations: Porting config from DBCP/c3p0 where negative or special values mean 'no timeout'; YAML arithmetic or environment-variable substitution producing -1; leftover test scaffolding values.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• validationTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• maxPoolSize cannot be less than 1
• minimumIdle cannot be negative
• Failed to load driver class ${driverClassName}

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