pentaho/pentaho-kettle · error · KettleStepException

SFTPPut.Error.SourceFileNameFieldMissing

Error message

SFTPPut.Error.SourceFileNameFieldMissing

What it means

Thrown by checkSourceFileField when the configured source filename field name is empty after environment substitution. The step cannot locate the source data without knowing which row field holds the filename. Raised during field validation before processing rows.

Solutions

  1. Open the SFTPPut dialog and select the field that contains the source filename.
  2. If a variable supplies the field name, define it (set variable step / kettle.properties) so substitution yields a non-empty value.
  3. Use 'Get Fields' in the dialog to populate field names from the incoming stream.
  4. Re-check the step after copying/cloning transformations to ensure settings persisted.

Example fix

// before (dialog config)
sourceFilenameField = ""; // or "${SRC_FIELD}" with SRC_FIELD undefined
// after
sourceFilenameField = "filename"; // or define SRC_FIELD=/path before run
Defensive patterns

Strategy: validation

Validate before calling

String fieldName = environmentSubstitute(sourceFilenameFieldSetting);
if (fieldName == null || fieldName.isEmpty()) {
  throw new IllegalStateException("SFTPPut: source filename field must be configured");
}

Try / catch

try {
  transform.execute();
} catch (KettleStepException e) {
  if (e.getMessage().contains("SourceFileNameFieldMissing")) {
    log.error("Configure the source filename field in the SFTPPut step");
  } else { throw e; }
}

Prevention

When it happens

Trigger: The 'Source filename fieldname' setting is blank in the step dialog (or the variable used for it substitutes to an empty string), and processRow invokes checkSourceFileField.

Common situations: Freshly configured step where the user forgot to pick the field; a KETTLE variable intended to hold the field name is undefined, substituting to empty; dialog settings lost after copying the step between transformations.

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/45221b9fcebf33f4. Report an issue: GitHub.

Appendix: source

Thrown at plugins/sftpput/impl/src/main/java/org/pentaho/di/trans/steps/sftpput/SFTPPut.java:269

          file.close();
        }
        if ( inputStream != null ) {
          inputStream.close();
        }
      } catch ( Exception e ) {
        // ignore this
      }
    }
    return true;
  }

  @VisibleForTesting
  void checkSourceFileField( String sourceFilenameFieldName, SFTPPutData data ) throws KettleStepException {
    // Sourcefilename field
    sourceFilenameFieldName = environmentSubstitute( sourceFilenameFieldName );
    if ( Utils.isEmpty( sourceFilenameFieldName ) ) {
      // source filename field is missing
      throw new KettleStepException( BaseMessages.getString( PKG, "SFTPPut.Error.SourceFileNameFieldMissing" ) );
    }

    data.indexOfSourceFileFieldName = getInputRowMeta().indexOfValue( sourceFilenameFieldName );
    if ( data.indexOfSourceFileFieldName == -1 ) {
      // source filename field is missing
      throw new KettleStepException( BaseMessages.getString(
        PKG, "SFTPPut.Error.CanNotFindField", sourceFilenameFieldName ) );
    }
  }

  @VisibleForTesting
  void checkRemoteFoldernameField( String remoteFoldernameFieldName, SFTPPutData data ) throws KettleStepException {
    // Remote folder fieldname
    remoteFoldernameFieldName = environmentSubstitute( remoteFoldernameFieldName );
    if ( Utils.isEmpty( remoteFoldernameFieldName ) ) {
      // remote folder field is missing
      throw new KettleStepException( BaseMessages.getString( PKG, "SFTPPut.Error.RemoteFolderNameFieldMissing" ) );
    }

View on GitHub (pinned to f3058517a1)