brettwooldridge/HikariCP · error · IllegalStateException

Could not match unit, got %s (from given value %s)

Error message

Could not match unit, got %s (from given value %s)

What it means

PropertyElf.parseDuration accepts a number plus a unit suffix of ms, s, m, h, or d when setting duration-typed properties (connectionTimeout etc. also accept long millis). Any other unit suffix makes the switch hit default and throw IllegalStateException naming the bad unit and value.

Source

Thrown at src/main/java/com/zaxxer/hikari/util/PropertyElf.java:264

   private static Optional<Duration> parseDuration(String value)
   {
      var matcher = DURATION_PATTERN.matcher(value);
      if (matcher.matches()) {
         var number = Long.parseLong(matcher.group("number"));
         var unit = matcher.group("unit");
         switch (unit) {
            case "ms":
               return Optional.of(Duration.ofMillis(number));
            case "s":
               return Optional.of(Duration.ofSeconds(number));
            case "m":
               return Optional.of(Duration.ofMinutes(number));
            case "h":
               return Optional.of(Duration.ofHours(number));
            case "d":
               return Optional.of(Duration.ofDays(number));
            default:
               throw new IllegalStateException(String.format("Could not match unit, got %s (from given value %s)", unit, value));
         }
      } else {
         return Optional.empty();
      }
   }
}

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Use only supported suffixes: ms, s, m, h, d (e.g. connectionTimeout=3000ms or 3s)
2. Or supply plain milliseconds as a number (legacy format)
3. Fix generated config templates that emit ns/us/sec/min suffixes

Example fix

# before
connectionTimeout=30sec
maxLifetime=30min

# after
connectionTimeout=30s
maxLifetime=30m

static final Set<String> UNITS = Set.of("ms","s","m","h","d");
static boolean validDuration(String v) {
    var m = Pattern.compile("(\\d+)(\\w*)").matcher(v);
    return m.matches() && (m.group(2).isEmpty() || UNITS.contains(m.group(2)));
}

When it happens

Trigger: Writing connectionTimeout=30sec, minimumIdle=10min, maxLifetime=1hour or 500us; locale-specific input like '30 s' with a space; copy-pasting durations from other tools that support units HikariCP does not.

Common situations: Config authored against Micrometer/ Dropwizard duration syntax (supports ns/us), documentation confusion, machine-generated config emitting unsupported units.

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
• validationTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m

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