pentaho/pentaho-kettle · error · KettleStepException

SFTPPut.Error.RemoteFolderNameFieldMissing

Error message

SFTPPut.Error.RemoteFolderNameFieldMissing

What it means

Thrown by checkRemoteFoldernameField when the configured remote folder field name is empty after environment substitution. When the remote directory is supplied per-row via a field, that field name must be specified. Raised during pre-flight validation from processRow.

Solutions

  1. Set the remote folder field in the SFTPPut dialog (or supply a static remote folder if per-row folders are not needed).
  2. Define the variable used for the field name so it substitutes to a real column name.
  3. Use 'Get Fields' to pick the correct column.
  4. Review the step's XML/ktr to confirm the setting survived save/load.

Example fix

// before
remoteFolderField = ""; // unset
// after
remoteFolderField = "remote_dir";
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
  transform.execute();
} catch (KettleStepException e) {
  if (e.getMessage().contains("RemoteFolderNameFieldMissing")) {
    log.error("Set the remote folder field in the SFTPPut dialog");
  } else { throw e; }
}

Prevention

When it happens

Trigger: The remote folder fieldname setting is blank (or its variable substitutes to empty) while the step expects a remote directory field, so checkRemoteFoldernameField throws.

Common situations: User left 'Remote folder field' unset in the dialog; variable for the field name undefined; configuration reset after migrating the transformation; stream mode switching cleared settings.

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/40a8020f3dd22387. Report an issue: GitHub.

Appendix: source

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

      // 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" ) );
    }

    data.indexOfRemoteDirectory = getInputRowMeta().indexOfValue( remoteFoldernameFieldName );
    if ( data.indexOfRemoteDirectory == -1 ) {
      // remote foldername field is missing
      throw new KettleStepException( BaseMessages.getString(
        PKG, "SFTPPut.Error.CanNotFindField", remoteFoldernameFieldName ) );
    }
  }

  @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

View on GitHub (pinned to f3058517a1)