pentaho/pentaho-kettle · error · KettleException

ExecSQLRow.Error.SQLFieldFieldMissing

Error message

ExecSQLRow.Error.SQLFieldFieldMissing

What it means

KettleException thrown by ExecSQLRow.processRow() when the step's 'SQL field name' setting (meta.getSqlFieldName()) is empty. The step executes SQL statements taken from a field of the incoming row, so it requires that field name to be configured before processing.

Solutions

1. Open the Execute SQL script step in Spoon and set the 'SQL field name' to an existing field of the incoming stream.
2. Programmatically, call setSqlFieldName("theField") on the ExecSQLRowMeta before running.
3. Verify the step metadata persisted correctly (check the ktr XML for the sql_field tag).

Example fix

// before
ExecSQLRowMeta meta = new ExecSQLRowMeta();
meta.setDatabaseMeta(dbMeta); // sqlFieldName never set
// after
ExecSQLRowMeta meta = new ExecSQLRowMeta();
meta.setDatabaseMeta(dbMeta);
meta.setSqlFieldName("sql_statement"); // must match an incoming field

if (meta.getSqlFieldName() == null || meta.getSqlFieldName().isEmpty()) {
  throw new IllegalStateException("ExecSQLRow: SQL field name must be set");
}

try { trans.execute(...); } catch (KettleException e) { if (e.getMessage().contains("SQLFieldFieldMissing")) { /* reconfigure step */ } }

When it happens

Trigger: Executing a transformation with an 'Execute SQL script' (ExecSQLRow) step whose 'sql field name' was never set in the step dialog, and processRow() calls Utils.isEmpty(meta.getSqlFieldName()) which returns true.

Common situations: Step metadata lost or not saved properly; transformation built programmatically without calling setSqlFieldName; legacy XML loaded where the sql field attribute was blank.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• DynamicSQLRow.Exception.SQLEmpty
• SQLFileOutputMeta.Exception.TableNotSpecified
• The tablename is not defined (empty)
• AccessInput.Exception.CouldnotFindField
• AccessInput.Log.NoField

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

Appendix: source

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

    Object[] row = getRow();
    if ( row == null ) { // no more input to be expected...

      setOutputDone();
      return false;
    }

    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 {

View on GitHub (pinned to f3058517a1)