brettwooldridge/HikariCP · critical · IllegalArgumentException

dataSource or dataSourceClassName or jdbcUrl is required.

Error message

dataSource or dataSourceClassName or jdbcUrl is required.

What it means

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).

Source

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

            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;
      }

      // keepalive time must larger than 30 seconds
      if (keepaliveTime != 0 && keepaliveTime < SECONDS.toMillis(30)) {

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Set jdbcUrl explicitly and verify it resolves non-empty in the failing environment (print effective config at startup)
2. If using HikariConfig(Properties)/property files, use HikariCP's exact camelCase key names (jdbcUrl, username, password...)
3. In Spring Boot, set spring.datasource.url or add an embedded DB (H2) for dev, and double-check active profiles
4. Alternatively provide dataSourceClassName, an external dataSource instance, or dataSourceJndiName — exactly one connection source
5. Enable debug logging of the effective configuration (HikariCP logs it at DEBUG) to confirm what was actually read

Example fix

// before
HikariConfig config = new HikariConfig();
config.setUsername("app");
// no jdbcUrl/dataSource* set -> IllegalArgumentException on start
HikariDataSource ds = new HikariDataSource(config);

// after
config.setJdbcUrl("jdbc:postgresql://dbhost:5432/appdb");
config.setUsername("app");
config.setPassword(System.getenv("DB_PASSWORD"));

boolean blank(String s) { return s == null || s.isBlank(); }
if (blank(jdbcUrl) && blank(dataSourceClassName) && blank(dataSourceJndiName) && dataSource == null) {
   throw new IllegalStateException("No connection source configured: set jdbcUrl, dataSourceClassName, dataSourceJndiName, or dataSource");
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• jdbcUrl is required with driverClassName.
• 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/dbc39b59b023acdb. Report an issue: GitHub.