brettwooldridge/HikariCP · error · IllegalArgumentException

minimumIdle cannot be negative

Error message

minimumIdle cannot be negative

What it means

HikariCP throws IllegalArgumentException when setMinimumIdle(int) receives a negative value. minIdle is the number of connections the pool tries to keep warm; a negative count is meaningless. 0 is legal (pool may shrink to zero idle connections), and values above maxPoolSize are not an error — validate() later raises minIdle to maxPoolSize with a warning.

Source

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

      if (maxPoolSize < 1) {
         throw new IllegalArgumentException("maxPoolSize cannot be less than 1");
      }
      this.maxPoolSize = maxPoolSize;
   }

   /** {@inheritDoc} */
   @Override
   public int getMinimumIdle()
   {
      return minIdle;
   }

   /** {@inheritDoc} */
   @Override
   public void setMinimumIdle(int minIdle)
   {
      if (minIdle < 0) {
         throw new IllegalArgumentException("minimumIdle cannot be negative");
      }
      this.minIdle = minIdle;
   }

   /**
    * Get the default password to use for DataSource.getConnection(username, password) calls.
    * @return the password
    */
   public String getPassword()
   {
      return credentials.get().getPassword();
   }

   /**
    * Set the default password to use for DataSource.getConnection(username, password) calls.
    * @param password the password
    */
   @Override

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Use a value between 0 and maxPoolSize; 0 lets the pool drain idle connections
2. For a fixed-size pool, set minIdle equal to maximumPoolSize
3. Trace the negative value to its source (env var, placeholder) and fix it there

Example fix

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

// after
config.setMinimumIdle(2);
// fixed-size pool:
config.setMinimumIdle(config.getMaximumPoolSize());

int minIdle = Math.max(0, configuredMinIdle);
if (minIdle > maxPoolSize) minIdle = maxPoolSize;
config.setMinimumIdle(minIdle);

When it happens

Trigger: Calling config.setMinimumIdle(n) with n < 0, or a properties/yml entry like minimumIdle=-1. Also triggered when a computed value (e.g. from a sizing formula or env var) underflows to negative.

Common situations: Using -1 to signal 'use default' (HikariCP convention: leave minIdle unset or use maxPoolSize for a fixed pool); config templating that substitutes an unset variable as -1; copy-paste from another pool's config dialect.

Related errors

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

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