pentaho/pentaho-kettle · error · KettleStepException

KettleStepException(cause) wrapping field conversion error…

Error message

KettleStepException(cause) wrapping field conversion error in getFields

What it means

In TextFileInputMeta.getFields(), while building the output row metadata (ValueMeta) for each configured field, any exception (e.g. invalid format masks, bad conversion settings) is rethrown as KettleStepException with the original exception as cause. The step cannot describe its output row layout without valid per-field conversion settings.

Solutions

Inspect the cause exception to see which field's conversion setup failed.
Correct the Format/Conversion mask for the failing field in the Fields tab (use valid SimpleDateFormat / DecimalFormat patterns).
Verify each field has a non-empty name and a compatible type for the given mask.
Remove exotic currency/grouping symbol settings or fix them to valid single characters.
Test the metadata via the step's 'Preview' before running the full transformation.

Example fix

// before: invalid mask for a Date field
field.setFormat("YYYY-mm-DD");
// after: valid SimpleDateFormat pattern
field.setFormat("yyyy-MM-dd");

Defensive patterns

Strategy: validation

Validate before calling

for (TextFileInputField f : meta.inputFields) {
  if (f.getName() == null || f.getName().isEmpty())
    throw new KettleStepException("Field name missing");
  if (f.getFormatMask() != null && f.getType() == ValueMetaInterface.TYPE_DATE)
    new SimpleDateFormat(f.getFormatMask()); // throws early on bad mask
}

Type guard

if (rowMeta == null || rowMeta.size() == 0) return false; // no usable output fields

Try / catch

try {
  meta.getFields(row, "stepName", info, transMeta, stepMeta, metaStore);
} catch (KettleStepException e) {
  log.logError("Field metadata error: " + e.getCause(), e);
  // fix masks/types or fall back to all-String fields
}

Prevention

Verify every field has a name and valid type/mask pair before saving the step.
Use Spoon's field preview to test conversion masks against real data.
Keep masks as SimpleDateFormat/DecimalFormat-valid patterns.
Avoid copying masks between locales without adjusting locale settings.

When it happens

Trigger: Calling getFields(...) (e.g. during row metadata resolution in the transformation) when a field's conversion mask, currency/decimal/grouping symbols, or format string makes constructing/validating the ValueMetaInterface throw.

Common situations: Typo'd date format masks (e.g. 'yyyy-MM-dd HH:mm' vs bad pattern chars); invalid number format patterns; locale issues after copying metadata between environments; null field names from incomplete dialog configuration.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/fileinput/text/TextFileInputMeta.java:586

        type = ValueMetaInterface.TYPE_STRING;
      }

      try {
        ValueMetaInterface v = ValueMetaFactory.createValueMeta( field.getName(), type );
        v.setLength( field.getLength() );
        v.setPrecision( field.getPrecision() );
        v.setOrigin( name );
        v.setConversionMask( field.getFormat() );
        v.setDecimalSymbol( field.getDecimalSymbol() );
        v.setGroupingSymbol( field.getGroupSymbol() );
        v.setCurrencySymbol( field.getCurrencySymbol() );
        v.setDateFormatLenient( content.dateFormatLenient );
        v.setDateFormatLocale( content.dateFormatLocale );
        v.setTrimType( field.getTrimType() );

        row.addValueMeta( v );
      } catch ( Exception e ) {
        throw new KettleStepException( e );
      }
    }
    if ( errorHandling.errorIgnored ) {
      if ( errorCountField != null && errorCountField.length() > 0 ) {
        ValueMetaInterface v = new ValueMetaInteger( errorCountField );
        v.setLength( ValueMetaInterface.DEFAULT_INTEGER_LENGTH, 0 );
        v.setOrigin( name );
        row.addValueMeta( v );
      }
      if ( errorFieldsField != null && errorFieldsField.length() > 0 ) {
        ValueMetaInterface v = new ValueMetaString( errorFieldsField );
        v.setOrigin( name );
        row.addValueMeta( v );
      }
      if ( errorTextField != null && errorTextField.length() > 0 ) {
        ValueMetaInterface v = new ValueMetaString( errorTextField );
        v.setOrigin( name );
        row.addValueMeta( v );

View on GitHub (pinned to f3058517a1)