{"record":{"id":"a62bfcf9342d379b","repo":"brettwooldridge/HikariCP","slug":"failed-to-read-property-file","errorCode":null,"errorMessage":"Failed to read property file","messagePattern":"Failed to read property file","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":1214,"sourceCode":"            // continue\n         }\n      }\n   }\n\n   private void loadProperties(String propertyFileName)\n   {\n      try (final var is = openPropertiesInputStream(propertyFileName)) {\n         if (is != null) {\n            var props = new Properties();\n            props.load(is);\n            PropertyElf.setTargetFromProperties(this, props);\n         }\n         else {\n            throw new IllegalArgumentException(\"Cannot find property file: \" + propertyFileName);\n         }\n      }\n      catch (IOException io) {\n         throw new RuntimeException(\"Failed to read property file\", io);\n      }\n   }\n\n   private InputStream openPropertiesInputStream(String propertyFileName) throws FileNotFoundException {\n      final var propFile = new File(propertyFileName);\n      if (propFile.isFile()) {\n         return new FileInputStream(propFile);\n      }\n      var propertiesInputStream = this.getClass().getResourceAsStream(propertyFileName);\n      if (propertiesInputStream == null) {\n        propertiesInputStream = this.getClass().getClassLoader().getResourceAsStream(propertyFileName);\n      }\n      return propertiesInputStream;\n   }\n\n   private String generatePoolName()\n   {\n      final var prefix = \"HikariPool-\";","sourceCodeStart":1196,"sourceCodeEnd":1232,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L1196-L1232","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause exception chained in the RuntimeException — it names the exact line/reason (e.g. IllegalArgumentException: malformed \\uxxxx encoding)","Fix or escape malformed content, especially backslash sequences: in .properties, backslashes must be doubled (\\\\) or replaced","If another process writes the file, write atomically (write temp file, then rename) so readers never see a partial file","Redeploy/rebuild the artifact if the jar or image layer is corrupted (verify with jar tf / md5sum)","As a robust alternative, load Properties yourself and pass them via new HikariConfig(Properties), adding your own diagnostics"],"exampleFix":"# before: password with lone \\u breaks Properties.load -> RuntimeException: Failed to read property file\ndatasource.password=pa\\ussword\n\n# after: escape the backslash\ndatasource.password=pa\\\\ussword\n\n// and read the cause when it happens:\n// catch (RuntimeException e) { e.getCause().printStackTrace(); }","handlingStrategy":"try-catch","validationCode":"// pre-flight: parse the file yourself; malformed \\u escapes surface here with a line number\nProperties p = new Properties();\ntry (var is = HikariConfig.class.getClassLoader().getResourceAsStream(path)) {\n   if (is == null) throw new IllegalStateException(\"missing \" + path);\n   p.load(is);\n   new HikariConfig(p);\n} catch (java.io.IOException | IllegalArgumentException e) {\n   throw new IllegalStateException(\"HikariCP property file unreadable: \" + path, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n   new HikariConfig(propertyFileName);\n} catch (RuntimeException e) {\n   if (\"Failed to read property file\".equals(e.getMessage()) && e.getCause() != null) {\n      log.error(\"Property file found but unreadable: {}\", e.getCause().getMessage(), e);\n   }\n   throw e;\n}","preventionTips":["Escape backslashes (\\\\) in .properties values — lone \\u sequences are the classic parser breaker","Write config files atomically (temp file + rename) when tools regenerate them","Always log the cause chain; the fixed message alone tells you nothing about the real IO failure"],"tags":["hikaricp","configuration","properties-file","io","encoding"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}