brettwooldridge/HikariCP · critical · IllegalStateException

cannot use driverClassName and dataSourceClassName together.

Error message

cannot use driverClassName and dataSourceClassName together.

What it means

validate() enforces that dataSourceClassName and driverClassName are mutually exclusive: a DataSource-based config (JDBC driver managed by HikariCP via DataSource) and a Driver-based config cannot coexist. When a dataSourceClassName is set (and no external dataSource instance was given) and driverClassName is also non-null, HikariCP logs an error and throws IllegalStateException. The comment in source notes this exact message is matched by a Spring Boot FailureAnalyzer, so the text is deliberately frozen.

Source

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

      connectionTestQuery = getNullIfEmpty(connectionTestQuery);
      transactionIsolationName = getNullIfEmpty(transactionIsolationName);
      dataSourceClassName = getNullIfEmpty(dataSourceClassName);
      dataSourceJndiName = getNullIfEmpty(dataSourceJndiName);
      driverClassName = getNullIfEmpty(driverClassName);
      jdbcUrl = getNullIfEmpty(jdbcUrl);

      // Check Data Source Options
      if (dataSource != null) {
         if (dataSourceClassName != null) {
            LOGGER.warn("{} - using dataSource and ignoring dataSourceClassName.", poolName);
         }
      }
      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();

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Pick one style: DataSource-based (dataSourceClassName + dataSourceProperties, no jdbcUrl/driverClassName) or Driver-based (jdbcUrl [+ driverClassName])
2. In Spring Boot, prefer spring.datasource.url and remove dataSourceClassName; do not set both
3. Grep all active config sources (yml, env vars, -D properties, config server) for the leftover key
4. Remember jdbcUrl is silently ignored (warn only) with dataSourceClassName, but driverClassName is a hard error

Example fix

# before
driverClassName=org.postgresql.Driver
dataSourceClassName=org.postgresql.ds.PGSimpleDataSource # IllegalStateException

# after (driver-based)
driverClassName=org.postgresql.Driver
jdbcUrl=jdbc:postgresql://db:5432/app
# dataSourceClassName removed

if (dataSourceClassName != null && driverClassName != null) {
   throw new IllegalStateException("Refusing to configure HikariCP: dataSourceClassName and driverClassName are mutually exclusive");
}
config.setDataSourceClassName(dataSourceClassName);
config.setDriverClassName(driverClassName);

When it happens

Trigger: Properties/yml containing both dataSourceClassName=org.postgresql.ds.PGSimpleDataSource and driverClassName=org.postgresql.Driver; Spring Boot externalized config where one property comes from application.yml and the other from an environment variable or profile that merges in; copy-pasting driver settings from another app into a DataSource-style config.

Common situations: Spring Boot: setting spring.datasource.url (which Boot translates to jdbcUrl/driver) while also setting dataSourceClassName; layered config servers adding driverClassName 'for completeness'; migration from Driver-based to DataSource-based config without removing the old key.

Related errors

• jdbcUrl is required with driverClassName.
• dataSource or dataSourceClassName or jdbcUrl is required.
• 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/4d98246a30877efe. Report an issue: GitHub.