What causes "ChangeFileEncoding.Error.TargetFileIsEmpty" in pentaho/pentaho-kettle?

Verify the 'Target filename field' setting in the Change File Encoding step dialog matches a real, populated input field.

pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.TargetFileIsEmpty

ChangeFileEncoding.Error.TargetFileIsEmpty

Error message

ChangeFileEncoding.Error.TargetFileIsEmpty

What it means

The Change File Encoding step wraps a KettleException because the target filename field read from the output row is empty. The step refuses to proceed when it cannot determine which file to write the re-encoded content to. The message includes the configured target filename field name to help locate the misconfiguration.

Solutions

Verify the 'Target filename field' setting in the Change File Encoding step dialog matches a real, populated input field.
Add or fix the upstream step that produces the target filename field so it emits a non-empty absolute path.
Use a 'Value Mapper' or 'If field value is null' step before this one to replace null/empty filenames with a valid default.
If the target path is static, disable the dynamic filename option and enter the filename directly instead of a field name.

Example fix

// before: reading an empty dynamic field
String targetFilename = data.inputRowMeta.getString( outputRow, data.indexOfTargetFileename );
// fix upstream: ensure the field is populated
// in a 'Get variables' / 'User Defined Java Expression' step:
//   target_file = ${Internal.Transformation.Filename.Directory} + "/output.txt"

Defensive patterns

Strategy: validation

Validate before calling

// Kettle: validate before the step
if ( row.getString( targetFilenameField, "" ).trim().isEmpty() ) {
  throw new KettleException( "target filename field is empty for row: " + row );
}

Prevention

Always verify the dynamic filename field exists in the incoming row layout before enabling dynamic mode.
Add a null/empty guard step upstream when filenames are computed dynamically.
Use fixed filenames where possible to avoid field-population surprises.

When it happens

Trigger: In processRow, when meta.getDynamicFilenameField() is set, the target filename is read from the output row via data.inputRowMeta.getString(outputRow, data.indexOfTargetFileename); if Utils.isEmpty(targetFilename) is true, this error is thrown.

Common situations: The 'Target filename field' in the step dialog points to a field that is not populated by the previous step; the field exists but contains null or empty string; a typo in the dynamic filename field mapping means a different (empty) column is read.

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/changefileencoding/ChangeFileEncoding.java:131

      if ( Utils.isEmpty( data.targetEncoding ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.TargetEncodingEmpty" ) );
      }

      // End If first
    }

    try {
      // get source filename
      String sourceFilename = data.inputRowMeta.getString( outputRow, data.indexOfFileename );
      if ( Utils.isEmpty( sourceFilename ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.SourceFileIsEmpty",
          meta.getDynamicFilenameField() ) );
      }

      // get target filename
      String targetFilename = data.inputRowMeta.getString( outputRow, data.indexOfTargetFileename );
      if ( Utils.isEmpty( targetFilename ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.TargetFileIsEmpty",
          meta.getTargetFilenameField() ) );
      }

      data.sourceFile = KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( sourceFilename );

      // Check if source file exists
      if ( !data.sourceFile.exists() ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ChangeFileEncoding.Error.SourceFileNotExists", sourceFilename ) );
      }

      // Check if source file is a file
      if ( data.sourceFile.getType() != FileType.FILE ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ChangeFileEncoding.Error.SourceFileNotAFile", sourceFilename ) );
      }

      // create directory only if not exists

View on GitHub (pinned to f3058517a1)