pentaho/pentaho-kettle · error · KettleException

PropertyOutput.Log.CanNotCreateParentFolder

Error message

PropertyOutput.Log.CanNotCreateParentFolder

What it means

createParentFolder attempts to create the parent directory of the output file when 'create parent folder' is enabled in the step metadata. If any exception occurs during folder creation (or the folder cannot be created), it logs and throws a KettleException using the CanNotCreateParentFolder message including the folder name, which then propagates through openNewFile.

Solutions

  1. Grant write/create permission on the parent directory for the user running the transformation (kitchen/pan or Spoon).
  2. Create the directory manually beforehand if it must be owned by a specific user.
  3. Verify the folder path derived from the filename is valid (no unexpanded variables, correct VFS scheme).
  4. Check filesystem mount status / disk space if the target is a network mount.

Example fix

// shell, before running the transformation
// before
mkdir: fails silently, step throws at runtime
// after
mkdir -p /data/output && chown pentaho:pentaho /data/output
Defensive patterns

Strategy: try-catch

Validate before calling

File parent = new File(filename).getAbsoluteFile().getParentFile();
if (!parent.exists() && !parent.getAbsoluteFile().getParentFile().canWrite()) {
    throw new IllegalStateException("Cannot create folder " + parent);
}

Try / catch

try {
    openNewFile();
} catch (KettleException e) {
    if (e.getMessage().contains("CanNotCreateParentFolder")) {
        // check permissions on the folder named in the message
    }
}

Prevention

When it happens

Trigger: meta.isCreateParentFolder() is true; resolveFile on the parent succeeds, but folder.exists() is false and createFolder() throws (permission denied, read-only filesystem, invalid path), or any Exception is raised in the try block.

Common situations: Writing to a path under a directory the Pentaho user cannot write to; creating deeply nested paths on a read-only mount; filename points to a filesystem root or an invalid VFS URI so parent resolution fails.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

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

Appendix: source

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

      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() ) {
            logDetailed( BaseMessages.getString( PKG, "PropertyOutput.Log.CanNotCreateParentFolder", parentfolder.getName().toString() ) );
          }
        }
      } catch ( Exception e ) {
        logError( BaseMessages.getString( PKG, "PropertyOutput.Log.CanNotCreateParentFolder", parentfolder.getName().toString() ) );
        throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.CanNotCreateParentFolder", parentfolder.getName().toString() ) );
      } finally {
        if ( parentfolder != null ) {
          try {
            parentfolder.close();
          } catch ( Exception ex ) { /* Ignore */
          }
        }
      }
    }
  }

  private boolean closeFile() {
    if ( data.file == null ) {
      return true;
    }
    boolean retval = false;
    try ( OutputStream propsFile = KettleVFS.getInstance( getTransMeta().getBowl() )
          .getOutputStream( data.file, false ) ) {

View on GitHub (pinned to f3058517a1)