brettwooldridge/HikariCP · critical · IllegalArgumentException

jdbcUrl is required with driverClassName.

Error message

jdbcUrl is required with driverClassName.

What it means

In validate(), when no external dataSource and no dataSourceClassName are set, a driverClassName without a jdbcUrl is an incomplete Driver-based configuration — HikariCP logs an error and throws IllegalArgumentException 'jdbcUrl is required with driverClassName.'. A driver alone tells HikariCP nothing about which database to connect to, and HikariCP does not synthesize URLs from driver defaults.

Source

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

         }
      }
      else if (dataSourceClassName != null) {
         if (driverClassName != null) {
            LOGGER.error("{} - cannot use driverClassName and dataSourceClassName together.", poolName);
            // NOTE: This exception text is referenced by a Spring Boot FailureAnalyzer, it should not be
            // changed without first notifying the Spring Boot developers.
            throw new IllegalStateException("cannot use driverClassName and dataSourceClassName together.");
         }
         else if (jdbcUrl != null) {
            LOGGER.warn("{} - using dataSourceClassName and ignoring jdbcUrl.", poolName);
         }
      }
      else if (jdbcUrl != null || dataSourceJndiName != null) {
         // ok
      }
      else if (driverClassName != null) {
         LOGGER.error("{} - jdbcUrl is required with driverClassName.", poolName);
         throw new IllegalArgumentException("jdbcUrl is required with driverClassName.");
      }
      else {
         LOGGER.error("{} - dataSource or dataSourceClassName or jdbcUrl is required.", poolName);
         throw new IllegalArgumentException("dataSource or dataSourceClassName or jdbcUrl is required.");
      }

      validateNumerics();

      if (LOGGER.isDebugEnabled() || unitTest) {
         logConfiguration();
      }
   }

   private void validateNumerics()
   {
      if (maxLifetime != 0 && maxLifetime < SECONDS.toMillis(30)) {
         LOGGER.warn("{} - maxLifetime is less than 30000ms, setting to default {}ms.", poolName, MAX_LIFETIME);
         maxLifetime = MAX_LIFETIME;

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Add jdbcUrl (Spring Boot: spring.datasource.url) with a valid JDBC URL for that driver
2. Check for empty/whitespace values — they are treated as unset (getNullIfEmpty normalization in validate)
3. Verify the property name spelling and the active profile/env in the failing environment
4. If you intended DataSource-based config, remove driverClassName and set dataSourceClassName + dataSourceProperties instead

Example fix

# before
driverClassName=org.postgresql.Driver
# jdbcUrl missing -> IllegalArgumentException

# after
driverClassName=org.postgresql.Driver
jdbcUrl=jdbc:postgresql://dbhost:5432/appdb

boolean blank(String s) { return s == null || s.isBlank(); }
if (driverClassName != null && blank(jdbcUrl)) {
   throw new IllegalStateException("driverClassName set but jdbcUrl is empty/missing");
}

When it happens

Trigger: Properties containing driverClassName but no jdbcUrl (and no dataSource/dataSourceClassName); setting jdbcUrl to an empty string — empty strings are normalized to null earlier in validate() so they do not count; Spring Boot where the URL property name is misspelled or the profile providing it is not active.

Common situations: Misspelled property key (jdbcurl vs jdbcUrl); the profile/env var supplying the URL not loaded in the deployed environment; empty-string placeholders from templating (e.g. JDBC_URL= set but blank); migrations where the URL moved keys and only the driver remained.

Related errors

• dataSource or dataSourceClassName or jdbcUrl is required.
• cannot use driverClassName and dataSourceClassName together.
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• idleTimeout cannot be negative
• maxPoolSize cannot be less than 1

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