pentaho/pentaho-kettle · error · KettleException

ProcessFiles.Error.SourceFilenameFieldMissing

Error message

ProcessFiles.Error.SourceFilenameFieldMissing

What it means

KettleException thrown by ProcessFiles.processRow on the first row when the 'source filename field' setting is empty. ProcessFiles copies/moves/deletes files named dynamically by fields in the incoming stream, so it requires the name of the field that holds the source file path; if the setting is missing the step cannot run. The check is Utils.isEmpty(meta.getDynamicSourceFileNameField()).

Solutions

  1. Open the Process Files step dialog and set 'Source filename fieldname' to an existing input field.
  2. If building metadata programmatically, call meta.setDynamicSourceFileNameField("source_filename") before adding the step.
  3. Re-save the transformation after fixing and verify the field exists in the incoming stream.

Example fix

// before
ProcessFilesMeta meta = new ProcessFilesMeta();
meta.setOperationType(ProcessFilesMeta.OPERATION_TYPE_COPY);
// after
ProcessFilesMeta meta = new ProcessFilesMeta();
meta.setDynamicSourceFileNameField("source_file");
meta.setDynamicTargetFileNameField("target_file");
meta.setOperationType(ProcessFilesMeta.OPERATION_TYPE_COPY);
Defensive patterns

Strategy: validation

Validate before calling

// Before executing, ensure the meta is complete
if (meta.getDynamicSourceFileNameField() == null || meta.getDynamicSourceFileNameField().isEmpty()) {
  throw new IllegalArgumentException("Process Files: source filename field must be set");
}

Try / catch

try { trans.execute(null); } catch (KettleException e) { if (e.getMessage().contains("SourceFilenameFieldMissing")) { log.error("Set 'Source filename fieldname' in Process Files step", e); } throw e; }

Prevention

When it happens

Trigger: The transformation runs the Process Files step with the 'Source filename fieldname' left blank in the step dialog, regardless of operation type.

Common situations: Step configured through metadata API or hand-edited ktr where the field was never set; importing an old transformation where the setting was lost.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/processfiles/ProcessFiles.java:67

    Trans trans ) {
    super( stepMeta, stepDataInterface, copyNr, transMeta, trans );
  }

  public boolean processRow( StepMetaInterface smi, StepDataInterface sdi ) throws KettleException {
    meta = (ProcessFilesMeta) smi;
    data = (ProcessFilesData) sdi;

    Object[] r = getRow(); // Get row from input rowset & set row busy!
    if ( r == null ) { // no more input to be expected...

      setOutputDone();
      return false;
    }
    if ( first ) {
      first = false;
      // Check is source filename field is provided
      if ( Utils.isEmpty( meta.getDynamicSourceFileNameField() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ProcessFiles.Error.SourceFilenameFieldMissing" ) );
      }
      // Check is target filename field is provided
      if ( meta.getOperationType() != ProcessFilesMeta.OPERATION_TYPE_DELETE
        && Utils.isEmpty( meta.getDynamicTargetFileNameField() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ProcessFiles.Error.TargetFilenameFieldMissing" ) );
      }

      // cache the position of the source filename field
      if ( data.indexOfSourceFilename < 0 ) {
        data.indexOfSourceFilename = getInputRowMeta().indexOfValue( meta.getDynamicSourceFileNameField() );
        if ( data.indexOfSourceFilename < 0 ) {
          // The field is unreachable !
          throw new KettleException( BaseMessages.getString( PKG, "ProcessFiles.Exception.CouldnotFindField", meta
            .getDynamicSourceFileNameField() ) );
        }
      }
      // cache the position of the source filename field
      if ( meta.getOperationType() != ProcessFilesMeta.OPERATION_TYPE_DELETE && data.indexOfTargetFilename < 0 ) {

View on GitHub (pinned to f3058517a1)