pentaho/pentaho-kettle · critical · KettleStepException

The tablename is not defined (empty)

Error message

The tablename is not defined (empty)

What it means

SQLFileOutput.init() substitutes variables for the configured table name and throws KettleStepException when the result is null or empty. The step writes SQL directly to a file targeting a specific table, so a table name is mandatory; without it no valid SQL could be generated. The throw happens during step initialization, before any rows are processed.

Solutions

  1. Open the SQL File Output step dialog and set the 'Target table' field to a non-empty value
  2. If using a variable like ${TABLE_NAME}, define it in the transformation run configuration, kettle.properties, or pass -param:TABLE_NAME=value to pan
  3. Verify with Get SQL / Preview that the table name resolves before running in production
  4. Re-save the step metadata if the field appears filled but the value was never persisted to the repository

Example fix

// before (step XML, empty table)
<tablename/>
// after
<tablename>DIM_CUSTOMER</tablename>
Defensive patterns

Strategy: validation

Validate before calling

// In the step dialog / before running:
String tableName = transMeta.environmentSubstitute( meta.getTablename() );
if ( tableName == null || tableName.trim().isEmpty() ) {
  throw new IllegalArgumentException( "SQL File Output: target table is empty; set 'Target table' or define the variable" );
}

Try / catch

// When running transformations programmatically:
try {
  trans.execute( null );
} catch ( KettleStepException e ) {
  if ( e.getMessage().contains( "tablename is not defined" ) ) {
    // correct step metadata or define variables, then retry
  } else { throw e; }
}

Prevention

When it happens

Trigger: The step's 'Target table' field is left blank in the step dialog, or the field contains only variable placeholders (e.g. ${TABLE_NAME}) that resolve to empty/null at runtime because the variable is not defined in the transformation, run configuration, or environment.

Common situations: Copy-pasting a step without filling in the target table; relying on a ${TABLE} variable that was set in one environment but not another (dev vs prod); running the transformation headless/pan without the variable defined on the command line; repository metadata where the tablename attribute was never saved.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/sqlfileoutput/SQLFileOutput.java:336

              } catch ( Exception ex ) { /* Ignore */
              }
            }
          }
        }

        if ( !meta.isDoNotOpenNewFileInit() ) {
          if ( !openNewFile() ) {
            logError( "Couldn't open file [" + buildFilename() + "]" );
            setErrors( 1L );
            stopAll();
          }
        }

        tableName = environmentSubstitute( meta.getTablename() );
        schemaName = environmentSubstitute( meta.getSchemaName() );

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

        schemaTable = data.db.getDatabaseMeta().getQuotedSchemaTableCombination( schemaName, tableName );

      } catch ( Exception e ) {
        logError( "An error occurred intialising this step: " + e.getMessage() );
        stopAll();
        setErrors( 1 );
      }

      return true;
    }
    return false;
  }

  public void dispose( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (SQLFileOutputMeta) smi;
    data = (SQLFileOutputData) sdi;

View on GitHub (pinned to f3058517a1)