brettwooldridge/HikariCP · error · IllegalArgumentException

validationTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m

Error message

validationTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}ms

What it means

HikariCP requires validationTimeout (how long a connection validity check may take) to be at least SOFT_TIMEOUT_FLOOR (250ms by default, via system property com.zaxxer.hikari.timeoutMs.floor). Unlike connectionTimeout there is no 0-means-infinite special case here — any value below the floor, including 0, throws IllegalArgumentException from setValidationTimeout(long). The rationale: validation queries must be given enough time to complete or healthy connections would be falsely evicted.

Source

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

    */
   public Credentials getCredentials()
   {
      return credentials.get();
   }

   /** {@inheritDoc} */
   @Override
   public long getValidationTimeout()
   {
      return validationTimeout;
   }

   /** {@inheritDoc} */
   @Override
   public void setValidationTimeout(long validationTimeoutMs)
   {
      if (validationTimeoutMs < SOFT_TIMEOUT_FLOOR) {
         throw new IllegalArgumentException("validationTimeout cannot be less than " + SOFT_TIMEOUT_FLOOR + "ms");
      }

      this.validationTimeout = validationTimeoutMs;
   }

   // ***********************************************************************
   //                     All other configuration methods
   // ***********************************************************************

   /**
    * Get the SQL query to be executed to test the validity of connections.
    *
    * @return the SQL query string, or null
    */
   public String getConnectionTestQuery()
   {
      return connectionTestQuery;
   }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Raise validationTimeout to >= 250ms; the default of 5000ms is fine unless you have measured validation latency
2. Do not try to disable validation timeout with 0 — there is no 'off' value
3. If your network/DB makes validation slow, fix that rather than shrinking the window

Example fix

// before
config.setValidationTimeout(100); // IllegalArgumentException

// after
config.setValidationTimeout(5000); // default, explicit

long FLOOR = Long.getLong("com.zaxxer.hikari.timeoutMs.floor", 250L);
if (validationTimeoutMs < FLOOR) {
   throw new IllegalArgumentException("validationTimeout must be >= " + FLOOR + "ms");
}
config.setValidationTimeout(validationTimeoutMs);

When it happens

Trigger: Calling config.setValidationTimeout(n) with 0 <= n < 250, or setting validationTimeout in properties/yml to a sub-250ms value — commonly 1, 50, or 100 in test configurations trying to fail fast.

Common situations: Copying a connectionTimeout-style tuning into validationTimeout; unit tests shrinking all timeouts; misunderstanding that 0 is not the 'disabled' value for this setting (use a large value or the default 5000ms instead).

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
• idleTimeout cannot be negative
• 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/7b6324cf4fd7c629. Report an issue: GitHub.