brettwooldridge/HikariCP · error · IllegalArgumentException

maxPoolSize cannot be less than 1

Error message

maxPoolSize cannot be less than 1

What it means

HikariCP requires at least one connection in the pool; setMaximumPoolSize(int) throws IllegalArgumentException for values < 1 because a zero-capacity pool could never satisfy a getConnection() call. This is a hard fail-fast check at setter time, before pool creation. To effectively 'pause' a pool you do not shrink it to 0 — you close it.

Source

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

   @Override
   public void setMaxLifetime(long maxLifetimeMs)
   {
      this.maxLifetime = maxLifetimeMs;
   }

   /** {@inheritDoc} */
   @Override
   public int getMaximumPoolSize()
   {
      return maxPoolSize;
   }

   /** {@inheritDoc} */
   @Override
   public void setMaximumPoolSize(int maxPoolSize)
   {
      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");
      }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Set a positive size; 10 is a common safe default for many apps
2. If the value is derived, guard the computation with Math.max(1, computed)
3. If pooling must be disabled, do not use HikariCP for that datasource at all rather than passing 0
4. Check the actual resolved value (env var, config server, profile) that reaches the setter

Example fix

// before
config.setMaximumPoolSize(0); // IllegalArgumentException

// after
config.setMaximumPoolSize(10);
// if computed:
config.setMaximumPoolSize(Math.max(1, cores * 2));

int size = Math.max(1, configuredMax);
config.setMaximumPoolSize(size);

When it happens

Trigger: Calling config.setMaximumPoolSize(0) or a negative value programmatically, via properties, or via Spring Boot spring.datasource.hikari.maximum-pool-size=0. Also occurs when the size is read from an environment variable or computed expression that evaluates to 0 (e.g. an unset var defaulting to 0).

Common situations: Env-var placeholder resolving to empty/0 in a deployment pipeline; dynamic sizing formulas (e.g. cores * multiplier) evaluating to 0 on small/odd-shaped containers; attempt to disable pooling by setting size to 0.

Related errors

• minimumIdle cannot be negative
• 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/4c078169d79e30a9. Report an issue: GitHub.