What causes "GPLoad.Exception.TargetTableNameMissing" in pentaho/pentaho-kettle?

Set the target table name in the GPLoad step dialog and save

pentaho/pentaho-kettle · error · KettleException

GPLoad.Exception.TargetTableNameMissing

Error message

GPLoad.Exception.TargetTableNameMissing

What it means

Thrown by GPLoad.getControlFileContents when the target table name is null while generating the gpload YAML control file. The method substitutes environment variables and validates the table name before writing the control file used by the gpload utility.

Solutions

Set the target table name in the GPLoad step dialog and save
Define any variable used for the table name (kettle.properties / run configuration) before execution
Validate configuration with the step's Test/preview before running the transformation

Example fix

// before
GPLoadMeta meta = new GPLoadMeta(); // targetTableName never set
meta.setTargetTableName( null );
// after
meta.setTargetTableName( "public.load_target" );

Defensive patterns

Strategy: validation

Validate before calling

// before createControlFile
String table = environmentSubstitute( meta.getTargetTableName() );
if ( table == null || table.trim().isEmpty() ) {
  throw new IllegalStateException( "GPLoad target table not configured" );
}

Type guard

boolean tableSet = meta.getTargetTableName() != null && !meta.getTargetTableName().trim().isEmpty();

Try / catch

try { String yaml = gpload.getControlFileContents(); } catch ( KettleException e ) { if ( e.getMessage().contains( "TargetTableNameMissing" ) ) { /* fix config */ } }

Prevention

Set the target table in the GPLoad dialog before saving
Define any table-name variables in kettle.properties per environment
Run testYAMLContents / the step's Test action before production runs

When it happens

Trigger: Calling getControlFileContents (directly or via testYAMLContents/createControlFile) when GPLoadMeta.targetTableName is null at execution time.

Common situations: Step not fully configured; table-name variable unset in the environment so substitution yields null/empty; transformation edited programmatically (metadata API) leaving the field null.

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

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

Appendix: source

Thrown at plugins/gpload/core/src/main/java/org/pentaho/di/trans/steps/gpload/GPLoad.java:152

    boolean[] updateColumn = meta.getUpdateColumn();

    // TODO: All this validation could be placed in it's own method,

    // table name validation
    DatabaseMeta databaseMeta = meta.getDatabaseMeta();
    String schemaName = meta.getSchemaName();
    String targetTableName = meta.getTableName();

    // TODO: What is schema name to a GreenPlum database?
    // Testing has been with an empty schema name
    // We will set it to an empty string if it is null
    // If it is not null then we will process what it is
    if ( schemaName == null ) {
      schemaName = "";
    }

    if ( targetTableName == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.TargetTableNameMissing" ) );
    }
    targetTableName = environmentSubstitute( targetTableName ).trim();
    if ( Utils.isEmpty( targetTableName ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.TargetTableNameMissing" ) );
    }

    // Schema name should be unquoted (gpload yaml parse error)
    schemaName = environmentSubstitute( schemaName );
    if ( Utils.isEmpty( schemaName ) ) {
      schemaName = databaseMeta.getPreferredSchemaName();
    }
    if ( Utils.isEmpty( schemaName ) ) {
      schemaName = "";
    } else {
      schemaName = schemaName + ".";
    }
    targetTableName = schemaName + databaseMeta.quoteField( targetTableName );

View on GitHub (pinned to f3058517a1)