pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.FilenameFieldMissing

ChangeFileEncoding.Error.FilenameFieldMissing

Error message

ChangeFileEncoding.Error.FilenameFieldMissing

What it means

ChangeFileEncoding processes rows where the source (and target) filenames come from fields in the incoming row stream. Before reading any row it validates the step configuration; it throws this localized KettleException when the 'filename field' setting — the input field that holds the source file path — is empty.

Solutions

1. Open the Change File Encoding step and set 'Filename fieldname' to the incoming field containing the source file path.
2. Ensure the field actually exists in the input stream (e.g. comes from a 'Get File Names' or previous step).
3. Re-save the transformation and re-open the step to confirm the setting persisted.

Example fix

// before
filenameField = null; // left blank in dialog
// after
filenameField = "source_file"; // incoming field holding the path

if (meta.getDynamicFilenameField() == null || meta.getDynamicFilenameField().isEmpty()) {
  throw new IllegalArgumentException("ChangeFileEncoding: 'Filename fieldname' must be set");
}
if (!inputRowMeta.getFieldNames().contains(meta.getDynamicFilenameField())) {
  throw new IllegalArgumentException("Field not in stream: " + meta.getDynamicFilenameField());
}

try {
  // execute transformation
} catch (KettleException e) {
  if (e.getMessage().contains("FilenameFieldMissing")) {
    // reconfigure the step's filename field
  } else { throw e; }
}

When it happens

Trigger: processRow, on the first row, when Utils.isEmpty(meta.getDynamicFilenameField()) is true: the 'Filename fieldname' box in the Change File Encoding dialog was left blank.

Common situations: Step added to the transformation but never configured; configuration lost after copy-pasting steps or version upgrades; user assumed a static filename could be entered where only a field name is accepted.

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.TargetFilenameFieldMissing
• 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/eeda5afacb913658. Report an issue: GitHub.

Appendix: source

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

    meta = (ChangeFileEncodingMeta) smi;
    data = (ChangeFileEncodingData) sdi;

    Object[] outputRow = getRow(); // Get row from input rowset & set row busy!
    if ( outputRow == null ) {
      // 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

View on GitHub (pinned to f3058517a1)