brettwooldridge/HikariCP · error · IllegalArgumentException
connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
Error message
connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}ms What it means
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.
Source
Thrown at src/main/java/com/zaxxer/hikari/HikariConfig.java:195
}
/** {@inheritDoc} */
@Override
public long getConnectionTimeout()
{
return connectionTimeout;
}
/** {@inheritDoc} */
@Override
public void setConnectionTimeout(long connectionTimeoutMs)
{
if (connectionTimeoutMs == 0) {
this.connectionTimeout = Integer.MAX_VALUE;
}
else if (connectionTimeoutMs < SOFT_TIMEOUT_FLOOR) {
throw new IllegalArgumentException("connectionTimeout cannot be less than " + SOFT_TIMEOUT_FLOOR + "ms");
}
else {
this.connectionTimeout = connectionTimeoutMs;
}
}
/** {@inheritDoc} */
@Override
public long getIdleTimeout()
{
return idleTimeout;
}
/** {@inheritDoc} */
@Override
public void setIdleTimeout(long idleTimeoutMs)
{
if (idleTimeoutMs < 0) {View on GitHub (pinned to a4d93f4f85)
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
Example fix
// before config.setConnectionTimeout(50); // IllegalArgumentException // after config.setConnectionTimeout(1000); // or: no timeout at all config.setConnectionTimeout(0); // means wait indefinitely
Defensive patterns
Strategy: validation
Validate before calling
long FLOOR = Long.getLong("com.zaxxer.hikari.timeoutMs.floor", 250L);
if (timeoutMs != 0 && timeoutMs < FLOOR) {
throw new IllegalArgumentException("connectionTimeout " + timeoutMs + "ms is below HikariCP floor " + FLOOR + "ms");
}
config.setConnectionTimeout(timeoutMs); Try / catch
catch (IllegalArgumentException e) {
if (e.getMessage().contains("connectionTimeout")) {
log.warn("connectionTimeout below floor; falling back to 30s", e);
config.setConnectionTimeout(30_000);
} else throw e;
} Prevention
- 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)
When it happens
Trigger: 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.
Common situations: 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.
Understand the failure class
- Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
Related errors
- idleTimeout cannot be negative
- 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/b87886b055e9f958.
Report an issue: GitHub.