{"record":{"id":"b87886b055e9f958","repo":"brettwooldridge/HikariCP","slug":"connectiontimeout-cannot-be-less-than-soft-timeo","errorCode":null,"errorMessage":"connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}ms","messagePattern":"connectionTimeout cannot be less than (.+?)ms","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":195,"sourceCode":"   }\n\n\n   /** {@inheritDoc} */\n   @Override\n   public long getConnectionTimeout()\n   {\n      return connectionTimeout;\n   }\n\n   /** {@inheritDoc} */\n   @Override\n   public void setConnectionTimeout(long connectionTimeoutMs)\n   {\n      if (connectionTimeoutMs == 0) {\n         this.connectionTimeout = Integer.MAX_VALUE;\n      }\n      else if (connectionTimeoutMs < SOFT_TIMEOUT_FLOOR) {\n         throw new IllegalArgumentException(\"connectionTimeout cannot be less than \" + SOFT_TIMEOUT_FLOOR + \"ms\");\n      }\n      else {\n         this.connectionTimeout = connectionTimeoutMs;\n      }\n   }\n\n   /** {@inheritDoc} */\n   @Override\n   public long getIdleTimeout()\n   {\n      return idleTimeout;\n   }\n\n   /** {@inheritDoc} */\n   @Override\n   public void setIdleTimeout(long idleTimeoutMs)\n   {\n      if (idleTimeoutMs < 0) {","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L177-L213","documentation":"HikariCP rejects any connectionTimeout below SOFT_TIMEOUT_FLOOR (250ms by default, tunable via system property com.zaxxer.hikari.timeoutMs.floor) because a shorter timeout would make getConnection() fail before the pool can realistically establish or hand out a connection. Setting the timeout to exactly 0 is a special case meaning 'wait forever' (internally Integer.MAX_VALUE). Any other value below the floor throws IllegalArgumentException at setter time, i.e. during configuration, before the pool starts.","triggerScenarios":"Calling config.setConnectionTimeout(n) or setting connectionTimeout=<n> in a properties file / Spring Boot application.yml where 0 < n < 250. Typical offenders: setConnectionTimeout(1), setConnectionTimeout(100), or unit tests that try to make tests fast by shrinking the timeout to a few milliseconds.","commonSituations":"Migrating from another pool (e.g. DBCP) whose timeout semantics differ; copying a 'speed up tests' snippet; YAML values expressed in the wrong unit (passing nanoseconds or microseconds instead of milliseconds); lowering the timeout to mask slow database startups.","solutions":["Raise connectionTimeout to at least 250ms (e.g. setConnectionTimeout(1000)); prefer seconds-scale values like 30000 for production","If the intent is 'never time out', pass 0 explicitly, which HikariCP maps to Integer.MAX_VALUE","Check for a mis-scaled unit: verify the number you pass is in milliseconds","Fix the underlying slowness (network, DB) instead of shrinking the timeout below the floor"],"exampleFix":"// before\nconfig.setConnectionTimeout(50); // IllegalArgumentException\n\n// after\nconfig.setConnectionTimeout(1000);\n// or: no timeout at all\nconfig.setConnectionTimeout(0); // means wait indefinitely","handlingStrategy":"validation","validationCode":"long FLOOR = Long.getLong(\"com.zaxxer.hikari.timeoutMs.floor\", 250L);\nif (timeoutMs != 0 && timeoutMs < FLOOR) {\n   throw new IllegalArgumentException(\"connectionTimeout \" + timeoutMs + \"ms is below HikariCP floor \" + FLOOR + \"ms\");\n}\nconfig.setConnectionTimeout(timeoutMs);","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) {\n   if (e.getMessage().contains(\"connectionTimeout\")) {\n      log.warn(\"connectionTimeout below floor; falling back to 30s\", e);\n      config.setConnectionTimeout(30_000);\n   } else throw e;\n}","preventionTips":["Centralize HikariCP config in one builder/validator function so timeouts are range-checked once","Express config in seconds in your own layer and convert to ms with a minimum clamp of 250","Assert resolved config values in a startup self-check (fail with a clear message before the pool is built)"],"tags":["hikaricp","configuration","timeout","connection-pool"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}