pentaho/pentaho-kettle · error · KettleStepException

TransformClassBase.Exception.UnableToFindFieldHelper

Error message

TransformClassBase.Exception.UnableToFindFieldHelper

What it means

Thrown by TransformClassBase.getFieldHelper when creating a FieldHelper for an In field fails because the field name does not exist in the step's input RowMeta (FieldHelper throws IllegalArgumentException for unknown fields). Wrapped in KettleStepException with the field type and name.

Solutions

  1. Fix the field name passed to get(Fields.In, ...) to match an actual input field (check case).
  2. Preview the input rows in Spoon to confirm the field exists in the stream.
  3. Add schema checks in the script (data.inputRowMeta.indexOfValue(name) >= 0) before accessing fields.

Example fix

// before
Object v = get(Fields.In, "CustName").getString(r); // field is 'cust_name'
// after
Object v = get(Fields.In, "cust_name").getString(r);
Defensive patterns

Strategy: validation

Validate before calling

// guard before accessing an input field in UDJC
if (data.inputRowMeta.indexOfValue("cust_name") < 0) throw new KettleStepException("Missing input field cust_name");

Type guard

boolean hasInputField(String name) { return data.inputRowMeta != null && data.inputRowMeta.indexOfValue(name) >= 0; }

Try / catch

try { FieldHelper fh = get(Fields.In, name); ... } catch (KettleStepException e) { logError("Input field not found: " + name, e); throw e; }

Prevention

When it happens

Trigger: Calling get(Fields.In, "fieldName") in UDJC script where fieldName is not a column of the incoming row stream.

Common situations: Typo in field name; upstream step schema changed and the column was renamed/dropped; case mismatch (row metadata is case-sensitive); running the script against a different input stream than designed.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/userdefinedjavaclass/TransformClassBase.java:620

  private final Map<String, FieldHelper> inFieldHelpers = new HashMap<String, FieldHelper>();
  private final Map<String, FieldHelper> infoFieldHelpers = new HashMap<String, FieldHelper>();
  private final Map<String, FieldHelper> outFieldHelpers = new HashMap<String, FieldHelper>();

  public enum Fields {
    In, Out, Info;
  }

  public FieldHelper get( Fields type, String name ) throws KettleStepException {
    FieldHelper fh;
    switch ( type ) {
      case In:
        fh = inFieldHelpers.get( name );
        if ( fh == null ) {
          try {
            fh = new FieldHelper( data.inputRowMeta, name );
          } catch ( IllegalArgumentException e ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "TransformClassBase.Exception.UnableToFindFieldHelper", type.name(), name ) );
          }
          inFieldHelpers.put( name, fh );
        }
        break;
      case Out:
        fh = outFieldHelpers.get( name );
        if ( fh == null ) {
          try {
            fh = new FieldHelper( data.outputRowMeta, name );
          } catch ( IllegalArgumentException e ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "TransformClassBase.Exception.UnableToFindFieldHelper", type.name(), name ) );
          }
          outFieldHelpers.put( name, fh );
        }
        break;
      case Info:

View on GitHub (pinned to f3058517a1)