pentaho/pentaho-kettle · error · KettleException

Error opening file [" + data.filename + "]!

Error message

Error opening file [" + data.filename + "]!

What it means

openNewFile wraps all file-opening work in a try-catch and rethrows any Exception as a KettleException with message "Error opening file [<filename>]!". This is a generic wrapper: the root cause (missing directory, permissions, invalid path, VFS error) is attached as the cause. It fires after the parent folder creation and before/while creating the file via the Kettle VFS layer.

Solutions

  1. Inspect the chained cause (e.getCause()) to find the real failure; fix permissions on the target directory.
  2. Verify the resolved filename is a valid path for the OS/VFS scheme (watch for unexpanded variables or special characters).
  3. Ensure the parent directory exists or enable 'Create parent folder' in the step settings.
  4. Check disk space and connectivity if the file is on a remote filesystem.

Example fix

// before
String file = "${UNSET_VAR}/out.properties"; // resolves with literal ${UNSET_VAR}
// after
String file = "/data/output/out.properties"; // or ensure the variable is defined at runtime
Defensive patterns

Strategy: try-catch

Validate before calling

File f = new File(filename);
File parent = f.getAbsoluteFile().getParentFile();
if (parent != null && !parent.canWrite()) {
    throw new IllegalStateException("No write permission on " + parent);
}

Try / catch

try {
    openNewFile();
} catch (KettleException e) {
    Throwable root = e;
    while (root.getCause() != null) root = root.getCause();
    logError("Failed to open " + data.filename + ": " + root.getMessage());
}

Prevention

When it happens

Trigger: processRow calls openNewFile(); any exception inside (KettleFileException from KettleVFS.getFileObject/createParentFolder/file creation, invalid URI characters in the filename, IO errors) is caught and rethrown with this message.

Common situations: Target directory is read-only or the process lacks write permission; filename contains characters invalid for the filesystem or VFS URI; network/SFTP target unreachable; disk full when creating the file.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/propertyoutput/PropertyOutput.java:186

    return data.previousFileName.equals( data.filename );
  }

  private void openNewFile() throws KettleException {
    try ( FileObject newFile = KettleVFS.getInstance( getTransMeta().getBowl() )
          .getFileObject( data.filename, getTransMeta() ) ) {
      data.pro = new Properties();
      data.KeySet.clear();

      data.file = newFile;
      if ( meta.isAppend() && data.file.exists() ) {
        data.pro.load( KettleVFS.getInputStream( data.file ) );
      }
      // Create parent folder if needed...
      createParentFolder();
      //save processing file
      data.previousFileName = data.filename;
    } catch ( Exception e ) {
      throw new KettleException( "Error opening file [" + data.filename + "]!", e );
    }
  }

  private void createParentFolder() throws KettleException {
    if ( meta.isCreateParentFolder() ) {
      FileObject parentfolder = null;
      try {
        // Do we need to create parent folder ?

        // Check for parent folder
        // Get parent folder
        parentfolder = data.file.getParent();
        if ( !parentfolder.exists() ) {
          if ( log.isDetailed() ) {
            logDetailed( BaseMessages.getString( PKG, "PropertyOutput.Log.ParentFolderExists", parentfolder.getName().toString() ) );
          }
          parentfolder.createFolder();
          if ( log.isDetailed() ) {

View on GitHub (pinned to f3058517a1)