pentaho/pentaho-kettle · error · KettleStepException

StringCut.Exception.FieldRequired

Error message

StringCut.Exception.FieldRequired

What it means

StringCut throws this KettleStepException in processRow() when a field configured as the cut input cannot be found in the incoming row stream. indexOfValue() returned -1, meaning the upstream step does not produce a field with that exact name.

Solutions

  1. Correct the field name in the String Cut step settings to match the actual incoming field (names are case-sensitive)
  2. Fix the upstream step so it emits the expected field
  3. Open the transformation in Spoon and re-map the input field via the step dialog
  4. Validate the row layout by previewing the upstream step's output

Example fix

// before
<field><in_stream_name>OldField</in_stream_name>...</field>
// after
<field><in_stream_name>RenamedField</in_stream_name>...</field>
Defensive patterns

Strategy: validation

Validate before calling

// before running the transformation, validate the field exists in the input layout
RowMetaInterface input = transMeta.getPrevStepFields(stepMeta);
for (String f : cutMeta.getFieldInStream()) {
  if (input.indexOfValue(f) < 0) {
    throw new IllegalStateException("Field not in stream: " + f);
  }
}

Try / catch

try {
  trans.execute(null);
  trans.waitUntilFinished();
} catch (KettleException e) {
  if (e.getMessage().contains("StringCut.Exception.FieldRequired")) {
    // fix step mapping: re-map or remove the missing field, then re-run
  }
}

Prevention

When it happens

Trigger: At the first processed row (fields are resolved from the first input row's RowMeta) when meta.getFieldInStream()[i] is not present in getInputRowMeta(), e.g. the field was renamed or removed upstream.

Common situations: Upstream step renamed/removed the field; case mismatch in field name; transformation edited so hop no longer carries the field; connecting the step to a different stream than designed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/stringcut/StringCut.java:133

    if ( r == null ) { // no more input to be expected...

      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;
      // What's the format of the output row?
      data.outputRowMeta = getInputRowMeta().clone();
      data.inputFieldsNr = data.outputRowMeta.size();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      data.inStreamNrs = new int[meta.getFieldInStream().length];
      for ( int i = 0; i < meta.getFieldInStream().length; i++ ) {
        data.inStreamNrs[i] = getInputRowMeta().indexOfValue( meta.getFieldInStream()[i] );
        if ( data.inStreamNrs[i] < 0 ) {
          throw new KettleStepException( BaseMessages.getString( PKG, "StringCut.Exception.FieldRequired", meta
            .getFieldInStream()[i] ) );
        }

        // check field type
        if ( getInputRowMeta().getValueMeta( data.inStreamNrs[i] ).getType() != ValueMetaInterface.TYPE_STRING ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "StringCut.Exception.FieldTypeNotString", meta.getFieldInStream()[i] ) );
        }
      }

      data.outStreamNrs = new String[meta.getFieldInStream().length];
      for ( int i = 0; i < meta.getFieldInStream().length; i++ ) {
        data.outStreamNrs[i] = environmentSubstitute( meta.getFieldOutStream()[i] );
      }

      data.cutFrom = new int[meta.getFieldInStream().length];
      data.cutTo = new int[meta.getFieldInStream().length];
      for ( int i = 0; i < meta.getFieldInStream().length; i++ ) {

View on GitHub (pinned to f3058517a1)