brettwooldridge/HikariCP · error · IllegalArgumentException

Cannot find property file: ${propertyFileName}

Error message

Cannot find property file: ${propertyFileName}

What it means

When HikariConfig is constructed with a property file name, loadProperties tries (in order) the filesystem, the class resource, and the classloader resource; if all return null it throws IllegalArgumentException 'Cannot find property file: <name>'. The name must be a path that resolves in at least one of those locations — a bare name is not implicitly prefixed with a directory.

Source

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

            }
            LOGGER.debug("{}{}", (prop + "................................................").substring(0, 32), value);
         }
         catch (Exception e) {
            // continue
         }
      }
   }

   private void loadProperties(String propertyFileName)
   {
      try (final var is = openPropertiesInputStream(propertyFileName)) {
         if (is != null) {
            var props = new Properties();
            props.load(is);
            PropertyElf.setTargetFromProperties(this, props);
         }
         else {
            throw new IllegalArgumentException("Cannot find property file: " + propertyFileName);
         }
      }
      catch (IOException io) {
         throw new RuntimeException("Failed to read property file", io);
      }
   }

   private InputStream openPropertiesInputStream(String propertyFileName) throws FileNotFoundException {
      final var propFile = new File(propertyFileName);
      if (propFile.isFile()) {
         return new FileInputStream(propFile);
      }
      var propertiesInputStream = this.getClass().getResourceAsStream(propertyFileName);
      if (propertiesInputStream == null) {
        propertiesInputStream = this.getClass().getClassLoader().getResourceAsStream(propertyFileName);
      }
      return propertiesInputStream;
   }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Verify where the file actually is at runtime: check the jar contents (jar tf) or the working directory of the process
2. Reference classpath resources with the correct relative path from the resources root, e.g. new HikariConfig("/config/db.properties") or the matching non-slash form
3. For filesystem files, use an absolute or verified relative path from the actual working directory
4. Alternatively load the Properties yourself (classloader resource) and pass them to new HikariConfig(Properties) — this sidesteps HikariCP's lookup rules

Example fix

// before
HikariConfig cfg = new HikariConfig("db.properties"); // file is in src/main/resources/config/ -> not found

// after
HikariConfig cfg = new HikariConfig("/config/db.properties");
// or explicit classpath loading
try (var is = HikariConfig.class.getClassLoader().getResourceAsStream("config/db.properties")) {
   Properties props = new Properties();
   props.load(is);
   HikariConfig cfg2 = new HikariConfig(props);
}

String name = "/config/hikari.properties";
boolean found = new java.io.File(name).isFile()
    || HikariConfig.class.getResource(name) != null
    || HikariConfig.class.getClassLoader().getResource(name) != null;
if (!found) throw new IllegalStateException("HikariCP property file not found in fs/classpath: " + name);
new HikariConfig(name);

When it happens

Trigger: new HikariConfig("app.properties") when the file is neither in the working directory nor on the classpath; wrong relative path (file sits in src/main/resources but the run directory differs); misspelled file name; path with a leading slash that mismatches the classloader lookup; packaging where the resource is filtered out.

Common situations: Working-directory assumptions breaking when running a jar vs from IDE; resources placed under a subfolder (src/main/resources/config/db.properties) but referenced as db.properties; Maven resource filtering or shade plugin excluding the file; the file present at build time but not in the Docker image layer.

Related errors

• Failed to load driver class ${driverClassName}
• Failed to read property file
• Failed to get driver instance for jdbcUrl={}
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• idleTimeout cannot be negative

AI-assisted analysis of brettwooldridge/HikariCP@a4d93f4f85 (2026-08-14). Data as JSON: /api/errors/d85e263ed50787fd. Report an issue: GitHub.