pentaho/pentaho-kettle · error · KettleException

Unhandled transformation type

Error message

Unhandled transformation type: ${transformationType}

What it means

When allocating row sets for step hop dispatch, Trans switches on transMeta.getTransformationType(). Only Normal, SerialSingleThreaded (implicitly handled) and SingleThreaded have cases; any other/unhandled TransformationType falls to default and throws this KettleException.

Solutions

  1. Upgrade the Kettle/PDI engine to a version supporting the transformation type in the file
  2. Re-save the transformation in a compatible Spoon version to normalize the type to Normal
  3. Check the <trans_type> element in the KTR XML and set it to 'Normal'

Example fix

// before (KTR XML)
<trans_type>UnusualType</trans_type>
// after
<trans_type>Normal</trans_type>
Defensive patterns

Strategy: try-catch

Validate before calling

TransformationType type = transMeta.getTransformationType();
if (type != TransformationType.Normal && type != TransformationType.SingleThreaded && type != TransformationType.SerialSingleThreaded) {
  throw new IllegalStateException("Unsupported transformation type: " + type);
}

Try / catch

try { trans.prepareExecution(); } catch (KettleException e) { if (e.getMessage().startsWith("Unhandled transformation type")) { /* upgrade or re-save KTR */ } throw e; }

Prevention

When it happens

Trigger: TransformationType enum containing a value not covered by the switch in Trans.prepareExecution — e.g. a new enum constant introduced by a plugin or a newer PDI format, or a corrupted transformationType in the KTR XML.

Common situations: Opening a KTR produced by a newer Pentaho version that defines a new transformation type in an older engine; programmatic construction with a custom/unexpected type; XML with invalid transformation_type attribute mapping.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/Trans.java:999

                Boolean batchingRowSet =
                  ValueMetaString.convertStringToBoolean( System.getProperty( Const.KETTLE_BATCHING_ROWSET ) );
                if ( batchingRowSet != null && batchingRowSet.booleanValue() ) {
                  rowSet = new BlockingBatchingRowSet( transMeta.getSizeRowset() );
                } else {
                  rowSet = new BlockingRowSet( transMeta.getSizeRowset() );
                }
                break;

              case SerialSingleThreaded:
                rowSet = new SingleRowRowSet();
                break;

              case SingleThreaded:
                rowSet = new QueueRowSet();
                break;

              default:
                throw new KettleException( "Unhandled transformation type: " + transMeta.getTransformationType() );
            }

            switch ( dispatchType ) {
              case TYPE_DISP_1_1:
                rowSet.setThreadNameFromToCopy( thisStep.getName(), 0, nextStep.getName(), 0 );
                break;
              case TYPE_DISP_1_N:
                rowSet.setThreadNameFromToCopy( thisStep.getName(), 0, nextStep.getName(), c );
                break;
              case TYPE_DISP_N_1:
                rowSet.setThreadNameFromToCopy( thisStep.getName(), c, nextStep.getName(), 0 );
                break;
              case TYPE_DISP_N_N:
                rowSet.setThreadNameFromToCopy( thisStep.getName(), c, nextStep.getName(), c );
                break;
              default:
                break;
            }

View on GitHub (pinned to f3058517a1)