What causes "throw new KettleStepException( e );" in pentaho/pentaho-kettle?

Inspect getCause() of the KettleStepException for the root exception.

pentaho/pentaho-kettle · error · KettleStepException

throw new KettleStepException( e );

Error message

throw new KettleStepException( e );

What it means

The catch-all in processRow: any unexpected Exception thrown while iterating files and building output rows is rethrown as a KettleStepException, aborting the step. The real cause is always in the wrapped exception.

Solutions

Inspect getCause() of the KettleStepException for the root exception.
Log/preview the incoming filename field values for malformed entries.
Verify VFS provider dependencies (e.g., SFTP/HTTP jars) are present.
Fix the specific file/permission problem indicated by the cause.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  processRow();
} catch (KettleStepException e) {
  Throwable root = e; while (root.getCause() != null) root = root.getCause();
  logError("Root cause: " + root, e);
  throw e;
}

Prevention

Always inspect the wrapped cause chain
Validate filename field values (valid paths/URIs) upstream
Install required VFS provider dependencies

When it happens

Trigger: Any non-Kettle exception during per-file processing: VFS resolution errors, null/invalid field values in the filename field, FileSystemException from file operations.

Common situations: Malformed filenames in the input field (bad URIs for VFS), unreadable directories, unexpected nulls from input rows, plugin/VFS provider missing.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/getfilenames/GetFileNames.java:258

        // See if we need to add the row number to the row...
        if ( meta.includeRowNumber() && !Utils.isEmpty( meta.getRowNumberField() ) ) {
          extraData[outputIndex++] = new Long( data.rownr );
        }

        data.rownr++;
        // Add row data
        outputRow = RowDataUtil.addRowData( outputRow, data.totalpreviousfields, extraData );
        // Send row
        putRow( data.outputRowMeta, outputRow );

        if ( meta.getRowLimit() > 0 && data.rownr >= meta.getRowLimit() ) { // limit has been reached: stop now.
          setOutputDone();
          return false;
        }

      }
    } catch ( Exception e ) {
      throw new KettleStepException( e );
    }

    data.filenr++;

    if ( checkFeedback( getLinesInput() ) ) {
      if ( log.isBasic() ) {
        logBasic( BaseMessages.getString( PKG, "GetFileNames.Log.NrLine", "" + getLinesInput() ) );
      }
    }

    return true;
  }

  private void handleMissingFiles() throws KettleException {
    if ( meta.isdoNotFailIfNoFile() && data.files.nrOfFiles() == 0 ) {
      logBasic( BaseMessages.getString( PKG, "GetFileNames.Log.NoFile" ) );
      return;
    }

View on GitHub (pinned to f3058517a1)