pentaho/pentaho-kettle · error · KettleException

ExecSQLRow.Exception.CouldnotFindField

Error message

ExecSQLRow.Exception.CouldnotFindField

What it means

KettleException thrown by ExecSQLRow.processRow() when the configured SQL field name cannot be found in the input row metadata (indexOfValue returns -1). The message includes the missing field name. The step cannot locate the column that is supposed to contain the SQL to execute.

Solutions

  1. Ensure an upstream step outputs a field whose name exactly (case-sensitively) matches the step's 'SQL field name'.
  2. Use a Select values / Rename step to produce a field with the expected name.
  3. Re-run 'Get Fields' in the step dialog after upstream changes and re-save the transformation.

Example fix

// before (field renamed upstream)
meta.setSqlFieldName("SQLQuery");
// after (match actual field or rename it upstream)
meta.setSqlFieldName("sql_query"); // or add Select values: rename SQLQuery -> sql_query
Defensive patterns

Strategy: validation

Validate before calling

String[] fields = inputRowMeta.getFieldNames();
if (java.util.Arrays.stream(fields).noneMatch(f -> f.equals(meta.getSqlFieldName()))) {
  throw new IllegalStateException("Field not in stream: " + meta.getSqlFieldName());
}

Try / catch

try { trans.execute(...); } catch (KettleException e) { if (e.getMessage().contains("CouldnotFindField")) { log.error("configure matching upstream field"); } }

Prevention

When it happens

Trigger: InputRowMeta.indexOfValue(meta.getSqlFieldName()) returns -1 at runtime because the upstream step doesn't emit a field with exactly that name (case-sensitive match).

Common situations: Renamed/deleted the source field upstream; case mismatch ('SQL' vs 'sql'); transformation edited so the field is no longer produced; running an older ktr against a changed stream.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/execsqlrow/ExecSQLRow.java:111

    if ( first ) { // we just got started

      first = false;

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Check is SQL field is provided
      if ( Utils.isEmpty( meta.getSqlFieldName() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ExecSQLRow.Error.SQLFieldFieldMissing" ) );
      }

      // cache the position of the field
      if ( data.indexOfSQLFieldname < 0 ) {
        data.indexOfSQLFieldname = this.getInputRowMeta().indexOfValue( meta.getSqlFieldName() );
        if ( data.indexOfSQLFieldname < 0 ) {
          // The field is unreachable !
          throw new KettleException( BaseMessages.getString( PKG, "ExecSQLRow.Exception.CouldnotFindField", meta
            .getSqlFieldName() ) );
        }
      }

    }

    // get SQL
    String sql = getInputRowMeta().getString( row, data.indexOfSQLFieldname );

    try {
      if ( meta.isSqlFromfile() ) {
        if ( Utils.isEmpty( sql ) ) {
          // empty filename
          throw new KettleException( BaseMessages.getString( PKG, "ExecSQLRow.Log.EmptySQLFromFile" ) );
        }
        if ( log.isDebug() ) {
          logDebug( BaseMessages.getString( PKG, "ExecSQLRow.Log.ExecutingSQLFromFile", sql ) );
        }

View on GitHub (pinned to f3058517a1)