{"record":{"id":"4d98246a30877efe","repo":"brettwooldridge/HikariCP","slug":"cannot-use-driverclassname-and-datasourceclassname","errorCode":null,"errorMessage":"cannot use driverClassName and dataSourceClassName together.","messagePattern":"cannot use driverClassName and dataSourceClassName together\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":1076,"sourceCode":"      connectionTestQuery = getNullIfEmpty(connectionTestQuery);\n      transactionIsolationName = getNullIfEmpty(transactionIsolationName);\n      dataSourceClassName = getNullIfEmpty(dataSourceClassName);\n      dataSourceJndiName = getNullIfEmpty(dataSourceJndiName);\n      driverClassName = getNullIfEmpty(driverClassName);\n      jdbcUrl = getNullIfEmpty(jdbcUrl);\n\n      // Check Data Source Options\n      if (dataSource != null) {\n         if (dataSourceClassName != null) {\n            LOGGER.warn(\"{} - using dataSource and ignoring dataSourceClassName.\", poolName);\n         }\n      }\n      else if (dataSourceClassName != null) {\n         if (driverClassName != null) {\n            LOGGER.error(\"{} - cannot use driverClassName and dataSourceClassName together.\", poolName);\n            // NOTE: This exception text is referenced by a Spring Boot FailureAnalyzer, it should not be\n            // changed without first notifying the Spring Boot developers.\n            throw new IllegalStateException(\"cannot use driverClassName and dataSourceClassName together.\");\n         }\n         else if (jdbcUrl != null) {\n            LOGGER.warn(\"{} - using dataSourceClassName and ignoring jdbcUrl.\", poolName);\n         }\n      }\n      else if (jdbcUrl != null || dataSourceJndiName != null) {\n         // ok\n      }\n      else if (driverClassName != null) {\n         LOGGER.error(\"{} - jdbcUrl is required with driverClassName.\", poolName);\n         throw new IllegalArgumentException(\"jdbcUrl is required with driverClassName.\");\n      }\n      else {\n         LOGGER.error(\"{} - dataSource or dataSourceClassName or jdbcUrl is required.\", poolName);\n         throw new IllegalArgumentException(\"dataSource or dataSourceClassName or jdbcUrl is required.\");\n      }\n\n      validateNumerics();","sourceCodeStart":1058,"sourceCodeEnd":1094,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L1058-L1094","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pick one style: DataSource-based (dataSourceClassName + dataSourceProperties, no jdbcUrl/driverClassName) or Driver-based (jdbcUrl [+ driverClassName])","In Spring Boot, prefer spring.datasource.url and remove dataSourceClassName; do not set both","Grep all active config sources (yml, env vars, -D properties, config server) for the leftover key","Remember jdbcUrl is silently ignored (warn only) with dataSourceClassName, but driverClassName is a hard error"],"exampleFix":"# before\ndriverClassName=org.postgresql.Driver\ndataSourceClassName=org.postgresql.ds.PGSimpleDataSource # IllegalStateException\n\n# after (driver-based)\ndriverClassName=org.postgresql.Driver\njdbcUrl=jdbc:postgresql://db:5432/app\n# dataSourceClassName removed","handlingStrategy":"validation","validationCode":"if (dataSourceClassName != null && driverClassName != null) {\n   throw new IllegalStateException(\"Refusing to configure HikariCP: dataSourceClassName and driverClassName are mutually exclusive\");\n}\nconfig.setDataSourceClassName(dataSourceClassName);\nconfig.setDriverClassName(driverClassName);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Choose one connection style per datasource and encode it in a single config module","In Spring Boot, rely on spring.datasource.url and never also set dataSourceClassName","Add a startup assertion that at most one of {dataSource, dataSourceClassName, jdbcUrl+driverClassName} is set"],"tags":["hikaricp","configuration","spring-boot","datasource","startup"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}