pentaho/pentaho-kettle · error · KettleException

Unable to read file '' + fileName + ''

Error message

Unable to read file '' + fileName + ''

What it means

EnvUtil.readPropertiesByFullPath loads a properties file from disk via FileInputStream; any IOException while opening or reading is wrapped in a KettleException with message "Unable to read file '<fileName>'". It is used by EnvUtil.readProperties to load environment/property files for Kettle initialization.

Solutions

1. Verify the file exists at the exact path passed (use absolute paths)
2. Check read permissions for the process user
3. Confirm the path is a regular file, not a directory
4. Call EnvUtil.readProperties with the correct KETTLE_HOME-relative location

Example fix

// before
EnvUtil.readProperties("kettle.properties"); // relative, wrong cwd
// after
File f = new File(System.getenv("KETTLE_HOME"), "kettle.properties");
if (!f.isFile()) { throw new FileNotFoundException(f.getAbsolutePath()); }
EnvUtil.readProperties(f.getAbsolutePath());

File f = new File(fileName);
if (!f.isFile() || !f.canRead()) { throw new IllegalArgumentException("Cannot read properties file: " + f.getAbsolutePath()); }

static boolean isReadableFile(String p) { File f = new File(p); return f.isFile() && f.canRead(); }

try {
  EnvUtil.readProperties(fileName);
} catch (KettleException e) {
  LOG.error("Failed to load properties from {}: {}", fileName, e.getCause().getMessage());
  throw new IllegalStateException("Missing environment configuration", e);
}

When it happens

Trigger: readProperties(fileName) called with a path that does not exist, lacks read permission, is a directory, or fails mid-read (I/O error). Note the exception message in the index shows quoting artifacts, but the actual message interpolates the real file path.

Common situations: Missing kettle.properties or custom env file at the referenced path; wrong working directory for relative paths; read-permission problems under restricted service accounts.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• AbstractFileErrorHandler.Exception.CouldNotCreateFileErrorHandlerForFile
• AbstractFileErrorHandler.Exception.CouldNotCloseFile
• AvroInputDialog.Error.KettleFileException
• context.getMessage()
• Could not close line number file

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/2db996f7c24b1bbd. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/util/EnvUtil.java:60

   * @param fileName
   *          the relative name of the properties file in the users kettle directory.
   * @return the map of properties.
   */
  public static Properties readProperties( final String fileName ) throws KettleException {
    if ( !new File( fileName ).exists() ) {
      return readPropertiesByFullPath( Const.getKettleDirectory() + Const.FILE_SEPARATOR + fileName );
    }
    return readPropertiesByFullPath( fileName );
  }

  private static Properties readPropertiesByFullPath( final String fileName ) throws KettleException {
    Properties props = new Properties();
    InputStream is = null;
    try {
      is = new FileInputStream( fileName );
      props.load( is );
    } catch ( IOException ioe ) {
      throw new KettleException( "Unable to read file '" + fileName + "'", ioe );
    } finally {
      if ( is != null ) {
        try {
          is.close();
        } catch ( IOException e ) {
          // ignore
        }
      }
    }
    return props;
  }

  /**
   * Adds the kettle properties the the global system properties.
   *
   * @throws KettleException
   *           in case the properties file can't be read.
   */

View on GitHub (pinned to f3058517a1)