What causes "ConcatFields.Error.UnsupportedEncoding" in pentaho/pentaho-kettle?

Set a standard encoding such as 'UTF-8' in the step's Content tab.

pentaho/pentaho-kettle · error · KettleStepException

ConcatFields.Error.UnsupportedEncoding

ConcatFields.Error.UnsupportedEncoding

Error message

ConcatFields.Error.UnsupportedEncoding

What it means

ConcatFields decodes the concatenated binary buffer into a String using the configured character encoding. If meta.getEncoding() names an encoding unsupported by the JVM, the UnsupportedEncodingException is wrapped in this KettleStepException.

Solutions

Set a standard encoding such as 'UTF-8' in the step's Content tab.
Check supported encodings with java.nio.charset.Charset.availableCharsets().
Clear the encoding field to let the step use the platform default.
Run on a JRE that includes the required charset provider.

Example fix

// before
meta.setEncoding( "utf8" );
// after
meta.setEncoding( "UTF-8" );

Defensive patterns

Strategy: validation

Validate before calling

try {
  java.nio.charset.Charset.forName( meta.getEncoding() );
} catch ( Exception e ) {
  throw new IllegalArgumentException( "Unsupported encoding: " + meta.getEncoding() );
}

Try / catch

try {
  step.processRow();
} catch ( KettleStepException e ) {
  if ( e.getMessage().contains( "UnsupportedEncoding" ) ) {
    logError( "Set a valid charset (e.g. UTF-8) in the step: " + e.getMessage() );
  }
}

Prevention

Use canonical charset names like UTF-8, ISO-8859-1.
Validate encodings with Charset.forName() before deploying.
Test transformations on the target JVM, not only the dev machine.

When it happens

Trigger: putRowFromStream (via processRow or checkAndWriteHeader) runs with data.hasEncoding true and meta.getEncoding() is not a valid charset name for the runtime JVM.

Common situations: Typo in encoding string (e.g., 'utf8' vs 'UTF-8' on strict JVMs, 'utf-16x'); transformation authored on a JVM with more charsets installed and run on a minimal JRE.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — 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/2e1ccf2bdf1797c9. Report an issue: GitHub.

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/concatfields/ConcatFields.java:217

    byte[] targetBinary = ( (ConcatFieldsOutputStream) data.writer ).read();
    if ( r == null && targetBinary == null ) {
      return null; // special condition of header/footer/split
    }

    Object[] outputRowData = prepareOutputRow( r );

    // add target field
    if ( outputRowData == null ) { // special condition of header/footer/split
      outputRowData = new Object[ data.outputRowMeta.size() ];
    }
    if ( targetBinary != null ) {
      if ( !data.hasEncoding ) {
        outputRowData[ data.posTargetField ] = new String( targetBinary );
      } else { // handle encoding
        try {
          outputRowData[ data.posTargetField ] = new String( targetBinary, meta.getEncoding() );
        } catch ( UnsupportedEncodingException e ) {
          throw new KettleStepException( BaseMessages.getString( PKG, "ConcatFields.Error.UnsupportedEncoding", ""
            + meta.getEncoding() ) );
        }
      }
    } else {
      outputRowData[ data.posTargetField ] = null;
    }

    putRow( data.outputRowMeta, outputRowData );
    return outputRowData;
  }

  // concat as a fast data dump (no formatting) and call putRow()
  // this method is only called from a normal line, never from header/footer/split stuff
  Object[] putRowFastDataDump( Object[] r ) throws KettleStepException {

    Object[] outputRowData = prepareOutputRow( r );

    StringBuilder targetString = new StringBuilder( data.targetFieldLengthFastDataDump ); // use a good capacity

View on GitHub (pinned to f3058517a1)