{"record":{"id":"dbc39b59b023acdb","repo":"brettwooldridge/HikariCP","slug":"datasource-or-datasourceclassname-or-jdbcurl-is-re","errorCode":null,"errorMessage":"dataSource or dataSourceClassName or jdbcUrl is required.","messagePattern":"dataSource or dataSourceClassName or jdbcUrl is required\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":1091,"sourceCode":"            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;\n      }\n\n      // keepalive time must larger than 30 seconds\n      if (keepaliveTime != 0 && keepaliveTime < SECONDS.toMillis(30)) {","sourceCodeStart":1073,"sourceCodeEnd":1109,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L1073-L1109","documentation":"This is validate()'s catch-all: none of dataSource, dataSourceClassName, jdbcUrl, or dataSourceJndiName is set, so HikariCP has no way to create connections and throws IllegalArgumentException 'dataSource or dataSourceClassName or jdbcUrl is required.' at pool start. It is the most common HikariCP startup failure and typically means the config never reached the pool (empty properties object, wrong property names, or unset env vars).","triggerScenarios":"new HikariDataSource() with a HikariConfig whose URL fields were never set; passing a Properties object whose keys are all wrong (HikariCP matches exact camelCase names like jdbcUrl); Spring Boot with spring.datasource.url absent everywhere (no embedded database on classpath and no explicit URL); dataSourceJndiName supplied as an empty string (normalized to null).","commonSituations":"Env var not exported in the container/CI so the URL placeholder resolves empty; using kebab-case or different property names than HikariCP expects when loading via HikariConfig(Properties); profiles: URL defined in application-prod.yml but prod profile not active; test suites constructing HikariConfig without URL for a testcontainer started later.","solutions":["Set jdbcUrl explicitly and verify it resolves non-empty in the failing environment (print effective config at startup)","If using HikariConfig(Properties)/property files, use HikariCP's exact camelCase key names (jdbcUrl, username, password...)","In Spring Boot, set spring.datasource.url or add an embedded DB (H2) for dev, and double-check active profiles","Alternatively provide dataSourceClassName, an external dataSource instance, or dataSourceJndiName — exactly one connection source","Enable debug logging of the effective configuration (HikariCP logs it at DEBUG) to confirm what was actually read"],"exampleFix":"// before\nHikariConfig config = new HikariConfig();\nconfig.setUsername(\"app\");\n// no jdbcUrl/dataSource* set -> IllegalArgumentException on start\nHikariDataSource ds = new HikariDataSource(config);\n\n// after\nconfig.setJdbcUrl(\"jdbc:postgresql://dbhost:5432/appdb\");\nconfig.setUsername(\"app\");\nconfig.setPassword(System.getenv(\"DB_PASSWORD\"));","handlingStrategy":"validation","validationCode":"boolean blank(String s) { return s == null || s.isBlank(); }\nif (blank(jdbcUrl) && blank(dataSourceClassName) && blank(dataSourceJndiName) && dataSource == null) {\n   throw new IllegalStateException(\"No connection source configured: set jdbcUrl, dataSourceClassName, dataSourceJndiName, or dataSource\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fail fast in your own bootstrap with a message naming the missing env var/property","Print the resolved effective configuration at startup and assert key fields are non-empty","When loading via HikariConfig(Properties), use HikariCP's exact camelCase keys (jdbcUrl, dataSourceClassName)","Wire a startup health check that opens one connection before declaring the app ready"],"tags":["hikaricp","configuration","jdbc-url","startup","spring-boot"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}