pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.TargetFilenameFieldMissing

ChangeFileEncoding.Error.TargetFilenameFieldMissing

Error message

ChangeFileEncoding.Error.TargetFilenameFieldMissing

What it means

ChangeFileEncoding requires both a source filename field and a target filename field from the incoming row. It throws this localized KettleException when the 'target filename field' configuration is empty, because the step would have nowhere to write the re-encoded file.

Solutions

1. Open the Change File Encoding step and set 'Target filename fieldname' to a field containing the output path (this can be the same field as the source for in-place conversion).
2. Ensure that field exists in the incoming row stream.
3. Re-save the transformation.

Example fix

// before
targetFilenameField = null;
// after
targetFilenameField = "target_file"; // or reuse "source_file" for in-place encoding

if (meta.getTargetFilenameField() == null || meta.getTargetFilenameField().isEmpty()) {
  throw new IllegalArgumentException("ChangeFileEncoding: 'Target filename fieldname' must be set");
}

try {
  // execute transformation
} catch (KettleException e) {
  if (e.getMessage().contains("TargetFilenameFieldMissing")) {
    // set target filename field and re-run
  } else { throw e; }
}

When it happens

Trigger: processRow, on the first row, when Utils.isEmpty(meta.getTargetFilenameField()) is true: the 'Target filename fieldname' box in the dialog is blank.

Common situations: Only the source field was configured; step cloned from a partially configured step; settings lost during an upgrade or XML/repository round-trip issue.

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

• ChangeFileEncoding.Error.FilenameFieldMissing
• ColumnExists.Error.TablenameFieldMissing
• GetFilesRowsCount.Log.NoField
• GetTableNames.Log.NoSchemaField
• HTTP.Log.NoField

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

Appendix: source

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

      // no more input to be expected...
      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;
      // get the RowMeta
      data.inputRowMeta = getInputRowMeta().clone();

      // Check is source filename field is provided
      if ( Utils.isEmpty( meta.getDynamicFilenameField() ) ) {
        logError( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.FilenameFieldMissing" ) );
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Error.FilenameFieldMissing" ) );
      }

      // Check is target filename field is provided
      if ( Utils.isEmpty( meta.getTargetFilenameField() ) ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ChangeFileEncoding.Error.TargetFilenameFieldMissing" ) );
      }

      // cache the position of the field
      data.indexOfFileename = data.inputRowMeta.indexOfValue( meta.getDynamicFilenameField() );
      if ( data.indexOfFileename < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.CouldnotFindField" ) + "["
            + meta.getDynamicFilenameField() + "]" );
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.CouldnotFindField",
          meta.getDynamicFilenameField() ) );
      }
      // cache the position of the field
      data.indexOfTargetFileename = data.inputRowMeta.indexOfValue( meta.getTargetFilenameField() );
      if ( data.indexOfTargetFileename < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.CouldnotFindField" ) + "["
            + meta.getTargetFilenameField() + "]" );

View on GitHub (pinned to f3058517a1)