pentaho/pentaho-kettle · error · KettleStepException

AnalyticQueryMeta.Exception.SubjectFieldNotFound

Error message

AnalyticQueryMeta.Exception.SubjectFieldNotFound

What it means

KettleStepException thrown from AnalyticQueryMeta.getFields() during row-layout resolution when one of the configured subject fields (the field each analytic aggregate like LAG/LEAD operates on) is not present in the incoming row metadata. The message lists the step name, the missing subject field, and all available field names to make the mismatch obvious.

Solutions

  1. Add the missing subject field upstream, or edit the Analytic Query step and pick an existing field from the printed list of available fields
  2. Check for field-name case differences and exact spelling between the upstream step and the configured subject field
  3. Run a 'Fields -> Update fields' / refresh field metadata in Spoon to re-sync the hop layout
  4. If a source schema changed, re-map the step configuration to the new column names

Example fix

// before (field renamed upstream)
subjectField[i] = "salary";
// after (match new upstream column)
subjectField[i] = "salary_amount";
Defensive patterns

Strategy: validation

Validate before calling

// Before executing, check that all subject fields exist on the hop
RowMetaInterface rmi = prevStepMeta.getStepMetaInterface().getFields(
  new RowMeta(), null, null, null, null, null, null);
for (String subject : analyticQueryMeta.getSubjectField()) {
  if (subject != null && rmi.searchValueMeta(subject) == null) {
    throw new IllegalStateException("Missing subject field: " + subject);
  }
}

Type guard

boolean fieldExists(RowMetaInterface rmi, String name) { return name != null && rmi.searchValueMeta(name) != null; }

Try / catch

try {
  transMeta.prepareExecution(new String[0]);
} catch (KettleStepException e) {
  if (e.getMessage().contains("SubjectFieldNotFound") || e.getMessage().contains("subject field")) {
    log.error("Configure the Analytic Query step with an existing field: " + e.getMessage());
  }
  throw e;
}

Prevention

When it happens

Trigger: getFields() iterates subjectField[i] and rowMetaInterface.searchValueData(subjectField[i]) returns null; thrown only when the subject field does not exist among r.getFieldNames().

Common situations: Renaming or deleting an upstream field without updating the Analytic Query step; the step sits on a hop whose stream no longer carries the field; case-sensitive field name mismatch; swapping a source table/CSV with different columns.

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/analyticquery/AnalyticQueryMeta.java:287

    for ( int i = 0; i < number_of_fields; i++ ) {

      int index_of_subject = -1;
      index_of_subject = r.indexOfValue( subjectField[i] );

      // if we found the subjectField in the RowMetaInterface, and we should....
      if ( index_of_subject > -1 ) {
        ValueMetaInterface vmi = r.getValueMeta( index_of_subject ).clone();
        vmi.setOrigin( origin );
        vmi.setName( aggregateField[i] );
        fields.addValueMeta( r.size() + i, vmi );
      } else {
        // we have a condition where the subjectField can't be found from the rowMetaInterface
        StringBuilder sbfieldNames = new StringBuilder();
        String[] fieldNames = r.getFieldNames();
        for ( int j = 0; j < fieldNames.length; j++ ) {
          sbfieldNames.append( "[" + fieldNames[j] + "]" + ( j < fieldNames.length - 1 ? ", " : "" ) );
        }
        throw new KettleStepException( BaseMessages.getString(
          PKG, "AnalyticQueryMeta.Exception.SubjectFieldNotFound", getParentStepMeta().getName(),
          subjectField[i], sbfieldNames.toString() ) );
      }
    }

    r.clear();
    // Add back to Row Meta
    r.addRowMeta( fields );
  }

  public String getXML() {
    StringBuilder retval = new StringBuilder( 500 );

    retval.append( "      <group>" ).append( Const.CR );
    for ( int i = 0; i < groupField.length; i++ ) {
      retval.append( "        <field>" ).append( Const.CR );
      retval.append( "          " ).append( XMLHandler.addTagValue( "name", groupField[i] ) );
      retval.append( "        </field>" ).append( Const.CR );

View on GitHub (pinned to f3058517a1)