pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Error.SourceFileIsEmpty

ChangeFileEncoding.Error.SourceFileIsEmpty

Error message

ChangeFileEncoding.Error.SourceFileIsEmpty

What it means

For each row the step reads the source filename from the configured field; if the value is null or empty it cannot open a file to convert and throws this localized KettleException naming the offending field.

Solutions

  1. Filter out rows with empty filename before this step (Filter rows: filename IS NOT NULL AND filename <> '').
  2. Fix the upstream step so it populates the filename field for every row (check file-list/table query logic).
  3. Provide a default path or use 'If field value is null' to set a value.
  4. Validate with a preview/data grid which rows carry empty filenames.

Example fix

// before: passing rows straight through with null paths
Table Input -> Change File Encoding
// after
Table Input -> Filter rows (filename IS NOT NULL AND filename != '') -> Change File Encoding
Defensive patterns

Strategy: validation

Validate before calling

// before the step, in a Filter rows / UDJC guard:
if (getFieldValue(r, "source_file") == null || getFieldValue(r, "source_file").toString().isEmpty()) {
  return false; // divert row to an error/log stream
}

Try / catch

try {
  // execute transformation
} catch (KettleException e) {
  if (e.getMessage().contains("SourceFileIsEmpty")) {
    // route empty-filename rows through a Filter rows step and re-run
  } else { throw e; }
}

Prevention

When it happens

Trigger: processRow per row: data.inputRowMeta.getString(outputRow, data.indexOfFileename) returns empty/null and Utils.isEmpty(sourceFilename) is true — i.e. an incoming row has no value in the filename field.

Common situations: Upstream 'Get File Names' matched no files so path fields are empty; rows generated from data (e.g. a Table Input) with null path columns; optional rows flowing through where a filename was never set; earlier steps overwriting the field with an empty string.

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

Appendix: source

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

      // if(Utils.isEmpty(data.sourceEncoding)) {
      // throw new KettleException(BaseMessages.getString(PKG, "ChangeFileEncoding.Exception.SourceEncodingEmpty"));
      // }
      // Check target encoding
      data.targetEncoding = environmentSubstitute( meta.getTargetEncoding() );

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

View on GitHub (pinned to f3058517a1)