pentaho/pentaho-kettle · error · KettleStepException

SFTPPut.Log.DestinatFolderNameFieldNameMissing

Error message

SFTPPut.Log.DestinatFolderNameFieldNameMissing

What it means

Thrown by SFTPPut.checkDestinationFolderField when the configured 'destination folder field name' setting is empty after environment substitution. The step needs a field in the incoming row whose value names the remote folder to move uploaded files into; without a field name it cannot proceed. It is a configuration error detected at runtime during processRow.

Solutions

  1. Open the SFTP Put step dialog and enter a valid incoming field name in the destination folder field name box
  2. Define the environment variable used there (kettle.properties or transformation settings) so it resolves to a non-empty value
  3. If you do not want folder moving, disable the 'move to folder' option instead of leaving the field blank

Example fix

// before: field name left as an unresolved variable
String destFolderField = "${DEST_FOLDER_FIELD}"; // resolves to ""
// after: verify before running the step
if ( Utils.isEmpty( environmentSubstitute( destFolderField ) ) ) {
  throw new KettleException( "Set DEST_FOLDER_FIELD to an existing input field name" );
}
Defensive patterns

Strategy: validation

Validate before calling

String resolved = transformationEnvironmentSubstitute( destFolderFieldName );
if ( resolved == null || resolved.trim().isEmpty() ) {
  throw new IllegalArgumentException( "SFTP Put: destination folder field name must not be empty" );
}

Try / catch

try {
  step.processRow();
} catch ( KettleStepException e ) {
  if ( e.getMessage().contains( "DestinatFolderNameFieldNameMissing" ) ) {
    logError( "Set the destination folder field name in the SFTP Put dialog" );
  } else { throw e; }
}

Prevention

When it happens

Trigger: The 'Move to folder field name' (destinationfolderFieldName) option is enabled in the SFTP Put step dialog but left blank, or it contains a variable that resolves to an empty string (e.g. ${UNSET_VAR}).

Common situations: Importing a transformation where the variable used for the field name was never defined in kettle.properties or the transformation's variables; copying a step config and clearing the field; toggling 'move to folder' on without filling the field name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

  @VisibleForTesting
  void checkRemoteFilenameField( String remoteFilenameFieldName, SFTPPutData data )
    throws KettleStepException {
    remoteFilenameFieldName = environmentSubstitute( remoteFilenameFieldName );
    if ( !Utils.isEmpty( remoteFilenameFieldName ) ) {
      data.indexOfRemoteFilename = getInputRowMeta().indexOfValue( remoteFilenameFieldName );
      if ( data.indexOfRemoteFilename == -1 ) {
        // remote file name field is set, but was not found
        throw new KettleStepException( BaseMessages.getString(
          PKG, "SFTPPut.Error.CanNotFindField", remoteFilenameFieldName ) );
      }
    }
  }

  @VisibleForTesting
  void checkDestinationFolderField( String realDestinationFoldernameFieldName, SFTPPutData data ) throws KettleStepException {
    realDestinationFoldernameFieldName = environmentSubstitute( realDestinationFoldernameFieldName );
    if ( Utils.isEmpty( realDestinationFoldernameFieldName ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "SFTPPut.Log.DestinatFolderNameFieldNameMissing" ) );
    }

    data.indexOfMoveToFolderFieldName = getInputRowMeta().indexOfValue( realDestinationFoldernameFieldName );
    if ( data.indexOfMoveToFolderFieldName == -1 ) {
      // move to folder field is missing
      throw new KettleStepException( BaseMessages.getString(
        PKG, "SFTPPut.Error.CanNotFindField", realDestinationFoldernameFieldName ) );
    }
  }

  @VisibleForTesting
  SFTPClient createSftpClient( String realServerName, String realServerPort, String realUsername,
                               String realKeyFilename, String realPassPhrase )
    throws KettleJobException, UnknownHostException {
    return new SFTPClient( getTransMeta().getBowl(),
      InetAddress.getByName( realServerName ), Const.toInt( realServerPort, 22 ), realUsername,
      realKeyFilename, realPassPhrase );

View on GitHub (pinned to f3058517a1)