What causes "The tablename is not defined (empty)" in pentaho/pentaho-kettle?

Enter a valid table name in the TableOutput step's 'Table name' field.

pentaho/pentaho-kettle · error · KettleStepException

The tablename is not defined (empty)

Error message

The tablename is not defined (empty)

What it means

After all table-name resolution paths (static name, table-name-in-field, partitioned naming), the computed tableName string is null or empty. The step cannot build an INSERT statement for an unnamed table, so it throws before consulting its prepared-statement cache.

Solutions

Enter a valid table name in the TableOutput step's 'Table name' field.
If using 'Table name in a field', ensure the field value is non-empty for every row.
Verify any environment variables used in the table name are defined at runtime.

Example fix

// before
meta.setTableName( "${TARGET_TABLE}" ); // TARGET_TABLE not defined -> ""
// after
meta.setTableName( "customer_output" ); // or define TARGET_TABLE in run config

Defensive patterns

Strategy: validation

Validate before calling

String tableName = resolveTableName(); // static, field, or partition logic
if ( tableName == null || tableName.trim().isEmpty() ) {
  throw new IllegalArgumentException( "Target table name is empty; fill in the Table name setting" );
}

Try / catch

try { processRow(); } catch ( KettleStepException e ) {
  if ( "The tablename is not defined (empty)".equals( e.getMessage() ) ) {
    // set a table name in step config or fix table-name field values
  }
}

Prevention

Always fill in the 'Table name' (or a reliable table-name field) before running
Verify environment variables used in table names are defined in the run configuration
Add an upstream validation step rejecting rows with empty table-name values

When it happens

Trigger: Utils.isEmpty(tableName) is true: the static 'Table name' setting is blank and no table-name field/partitioning logic produced a name, or the table name field's value is empty in the current row.

Common situations: Forgetting to fill in the 'Table name' in the dialog; the table-name field contains an empty string or null for some rows; environment variable in the table name unset so it substitutes to empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tableoutput/TableOutput.java:237

          + "_" + data.dateFormater.format( (Date) partitioningValueData );
      insertRowData = r;
    } else {
      tableName = data.tableName;
      insertRowData = r;
    }

    if ( meta.specifyFields() ) {
      //
      // The values to insert are those in the fields sections
      //
      insertRowData = new Object[data.valuenrs.length];
      for ( int idx = 0; idx < data.valuenrs.length; idx++ ) {
        insertRowData[idx] = r[data.valuenrs[idx]];
      }
    }

    if ( Utils.isEmpty( tableName ) ) {
      throw new KettleStepException( "The tablename is not defined (empty)" );
    }

    insertStatement = data.preparedStatements.get( tableName );
    if ( insertStatement == null ) {
      String sql =
        data.db
          .getInsertStatement( environmentSubstitute( meta.getSchemaName() ), tableName, data.insertRowMeta );
      if ( log.isDetailed() ) {
        logDetailed( "Prepared statement : " + sql );
      }
      insertStatement = data.db.prepareSQL( sql, meta.isReturningGeneratedKeys() );
      data.preparedStatements.put( tableName, insertStatement );
    }

    try {
      // For PG & GP, we add a savepoint before the row.
      // Then revert to the savepoint afterwards... (not a transaction, so hopefully still fast)
      //

View on GitHub (pinned to f3058517a1)