What causes "ChangeFileEncoding.Exception.TargetEncodingEmpty" in pentaho/pentaho-kettle?

Set 'Target encoding' in the step dialog to a valid charset name (e.g. UTF-8).

pentaho/pentaho-kettle · error · KettleException

ChangeFileEncoding.Exception.TargetEncodingEmpty

ChangeFileEncoding.Exception.TargetEncodingEmpty

Error message

ChangeFileEncoding.Exception.TargetEncodingEmpty

What it means

After substituting variables in the target encoding setting, the step validates it is non-empty and throws this localized KettleException when no target character encoding (e.g. UTF-8, ISO-8859-1) has been configured. Without it the step cannot know how to write the converted file.

Solutions

Set 'Target encoding' in the step dialog to a valid charset name (e.g. UTF-8).
If a variable is used, define it in the transformation settings, kettle.properties, or pass it via -param on pan/kitchen.
Verify the resolved value with 'Show variables' or logging before the step.
Note the source-encoding check is commented out in the code, so only the target encoding is validated here.

Example fix

// before
targetEncoding = ${UNDEFINED_VAR}; // resolves to empty
// after
targetEncoding = UTF-8; // or define ${TARGET_ENC}=UTF-8

Defensive patterns

Strategy: validation

Validate before calling

String enc = transMeta.environmentSubstitute(meta.getTargetEncoding());
if (enc == null || enc.isEmpty()) {
  throw new IllegalArgumentException("Target encoding must be set (e.g. UTF-8)");
}
Charset.forName(enc); // also validate it is a supported charset

Try / catch

try {
  // execute transformation
} catch (KettleException e) {
  if (e.getMessage().contains("TargetEncodingEmpty")) {
    // set target encoding / define the variable
  } else { throw e; }
}

Prevention

Always set a concrete charset like UTF-8
When using variables, define them in kettle.properties or pass via -param
Validate the charset name with Charset.forName at config time

When it happens

Trigger: processRow on the first row when Utils.isEmpty(data.targetEncoding) is true — 'Target encoding' empty in the dialog or the variable used for it (e.g. ${TARGET_ENC}) resolves to empty/null.

Common situations: Encoding field left blank; environment variable or parameter not defined in the runtime environment (kitchen/pan without the parameter set); variable misspelled so it substitutes to empty.

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

Appendix: source

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

      if ( data.indexOfTargetFileename < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.CouldnotFindField" ) + "["
            + meta.getTargetFilenameField() + "]" );
        throw new KettleException( BaseMessages.getString( PKG, "ChangeFileEncoding.Exception.CouldnotFindField",
          meta.getTargetFilenameField() ) );
      }

      // Check source encoding
      data.sourceEncoding = environmentSubstitute( meta.getSourceEncoding() );

      // 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() ) );

View on GitHub (pinned to f3058517a1)