{"record":{"id":"3f11e14e3131c8b6","repo":"brettwooldridge/HikariCP","slug":"jdbcurl-is-required-with-driverclassname","errorCode":null,"errorMessage":"jdbcUrl is required with driverClassName.","messagePattern":"jdbcUrl is required with driverClassName\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":1087,"sourceCode":"         }\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();\n\n      if (LOGGER.isDebugEnabled() || unitTest) {\n         logConfiguration();\n      }\n   }\n\n   private void validateNumerics()\n   {\n      if (maxLifetime != 0 && maxLifetime < SECONDS.toMillis(30)) {\n         LOGGER.warn(\"{} - maxLifetime is less than 30000ms, setting to default {}ms.\", poolName, MAX_LIFETIME);\n         maxLifetime = MAX_LIFETIME;","sourceCodeStart":1069,"sourceCodeEnd":1105,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L1069-L1105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add jdbcUrl (Spring Boot: spring.datasource.url) with a valid JDBC URL for that driver","Check for empty/whitespace values — they are treated as unset (getNullIfEmpty normalization in validate)","Verify the property name spelling and the active profile/env in the failing environment","If you intended DataSource-based config, remove driverClassName and set dataSourceClassName + dataSourceProperties instead"],"exampleFix":"# before\ndriverClassName=org.postgresql.Driver\n# jdbcUrl missing -> IllegalArgumentException\n\n# after\ndriverClassName=org.postgresql.Driver\njdbcUrl=jdbc:postgresql://dbhost:5432/appdb","handlingStrategy":"validation","validationCode":"boolean blank(String s) { return s == null || s.isBlank(); }\nif (driverClassName != null && blank(jdbcUrl)) {\n   throw new IllegalStateException(\"driverClassName set but jdbcUrl is empty/missing\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate config completeness (url + driver pairing) before constructing the pool","Beware empty-string env vars — treat blank as missing in your config layer (HikariCP does)","Include the effective config in error diagnostics at startup"],"tags":["hikaricp","configuration","jdbc-url","startup","spring-boot"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}