brettwooldridge/HikariCP · error · RuntimeException

Failed to read property file

Error message

Failed to read property file

What it means

loadProperties found the property file (openPropertiesInputStream returned a stream) but reading it failed with an IOException — the stream threw while being parsed by Properties.load, or closing it failed. HikariCP wraps the IOException in a RuntimeException with the fixed message 'Failed to read property file'; the original exception is attached as the cause and contains the actual reason (malformed content, stream closed, encoding issue, etc.). Note this is distinct from error 18: the file was located, but its contents could not be read.

Source

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

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

   private String generatePoolName()
   {
      final var prefix = "HikariPool-";

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Inspect the cause exception chained in the RuntimeException — it names the exact line/reason (e.g. IllegalArgumentException: malformed \uxxxx encoding)
2. Fix or escape malformed content, especially backslash sequences: in .properties, backslashes must be doubled (\\) or replaced
3. If another process writes the file, write atomically (write temp file, then rename) so readers never see a partial file
4. Redeploy/rebuild the artifact if the jar or image layer is corrupted (verify with jar tf / md5sum)
5. As a robust alternative, load Properties yourself and pass them via new HikariConfig(Properties), adding your own diagnostics

Example fix

# before: password with lone \u breaks Properties.load -> RuntimeException: Failed to read property file
datasource.password=pa\ussword

# after: escape the backslash
datasource.password=pa\\ussword

// and read the cause when it happens:
// catch (RuntimeException e) { e.getCause().printStackTrace(); }

// pre-flight: parse the file yourself; malformed \u escapes surface here with a line number
Properties p = new Properties();
try (var is = HikariConfig.class.getClassLoader().getResourceAsStream(path)) {
   if (is == null) throw new IllegalStateException("missing " + path);
   p.load(is);
   new HikariConfig(p);
} catch (java.io.IOException | IllegalArgumentException e) {
   throw new IllegalStateException("HikariCP property file unreadable: " + path, e);
}

try {
   new HikariConfig(propertyFileName);
} catch (RuntimeException e) {
   if ("Failed to read property file".equals(e.getMessage()) && e.getCause() != null) {
      log.error("Property file found but unreadable: {}", e.getCause().getMessage(), e);
   }
   throw e;
}

When it happens

Trigger: A properties file with malformed Unicode escapes (\u not followed by 4 hex digits) throws during Properties.load; a classpath resource stream that becomes invalid mid-read (broken jar/overlay filesystem in a container); a file replaced/truncated concurrently while being read; disk or NFS-level read errors on the file.

Common situations: Passwords or values containing literal \u sequences (unescaped backslashes are a classic properties-file pitfall); Docker overlayfs or corrupted fat-jars producing failing streams; files being written by another process (config reload tooling) at the moment of read; encoding mismatches when the file was edited with binary characters.

Related errors

• Cannot find property file: ${propertyFileName}
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• idleTimeout cannot be negative
• maxPoolSize cannot be less than 1
• minimumIdle cannot be negative

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