pentaho/pentaho-kettle · error · KettleStepException

DatabaseJoin.Exception.FieldNotFound (with parameter field…

Error message

DatabaseJoin.Exception.FieldNotFound (with parameter field name)

What it means

DatabaseJoin.lookupValues resolves each configured parameter field's index in the incoming row; if a parameter field name is not present in the row, it throws KettleStepException 'DatabaseJoin.Exception.FieldNotFound' with the field name. The SQL cannot be parameterized without all parameter values present, so the row is rejected and the step fails.

Solutions

Open the Database Join dialog and correct the parameter field names to match the actual incoming fields exactly.
Inspect the incoming row layout (preview upstream step) and add/restore the missing field.
Add a 'Select values' step upstream to add/alias the expected field name.
Verify the hop connects the intended source step.

Example fix

// before: parameter field 'cust_id' but upstream outputs 'customer_id'
meta.setParameterField(new String[] { "cust_id" });
// after: match the real upstream field name
meta.setParameterField(new String[] { "customer_id" });

Defensive patterns

Strategy: validation

Validate before calling

RowMetaInterface incoming = ...; // preview upstream row
for (String param : meta.getParameterField()) {
  if (incoming.indexOfValue(param) < 0)
    throw new IllegalArgumentException("Parameter field missing from stream: " + param);
}

Try / catch

try { step.processRow(); }
catch (KettleStepException e) {
  if (e.getMessage().contains("FieldNotFound")) {
    String field = extractQuoted(e.getMessage()); // reconfigure parameter fields
  }
}

Prevention

Verify parameter field names against an upstream preview before running
Use Select values to alias fields rather than relying on upstream names
Re-check step config after any upstream field rename

When it happens

Trigger: processRow -> lookupValues when meta.getParameterField()[i] does not match any column of the input row (rowMeta.indexOfValue returns -1): field renamed upstream, deleted, or a typo in the 'Insert field' parameter list.

Common situations: Upstream step changed/renamed its output fields; connector hop wired from the wrong stream; case-sensitive field name mismatch; copy/paste of a transformation where an alias was lost.

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/6a585d0da82d0820. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/databasejoin/DatabaseJoin.java:71

        first = false;
        prepareSQL( meta, data );
        data.outputRowMeta = rowMeta.clone();
        meta.getFields( getTransMeta().getBowl(),
            data.outputRowMeta, getStepname(), new RowMetaInterface[] { meta.getTableFields(), }, null, this,
            repository, metaStore );

        data.lookupRowMeta = new RowMeta();

        if ( log.isDetailed() ) {
          logDetailed( BaseMessages.getString( PKG, "DatabaseJoin.Log.CheckingRow" ) + rowMeta.getString( rowData ) );
        }

        data.keynrs = new int[meta.getParameterField().length];

        for ( int i = 0; i < meta.getParameterField().length; i++ ) {
          data.keynrs[i] = rowMeta.indexOfValue( meta.getParameterField()[i] );
          if ( data.keynrs[i] < 0 ) {
            throw new KettleStepException( BaseMessages.getString( PKG, "DatabaseJoin.Exception.FieldNotFound", meta
                .getParameterField()[i] ) );
          }

          data.lookupRowMeta.addValueMeta( rowMeta.getValueMeta( data.keynrs[i] ).clone() );
        }
      }

      // Construct the parameters row...
      Object[] lookupRowData = new Object[data.lookupRowMeta.size()];
      for ( int i = 0; i < data.keynrs.length; i++ ) {
        lookupRowData[i] = rowData[data.keynrs[i]];
      }

      // Set the values on the prepared statement (for faster exec.)
      rs = data.db.openQuery( data.pstmt, data.lookupRowMeta, lookupRowData );

      // Get a row from the database...
      //

View on GitHub (pinned to f3058517a1)