pentaho/pentaho-kettle · error · KettleException

GPLoad.Exception.UpdateColumnsNeeded

Error message

GPLoad.Exception.UpdateColumnsNeeded

What it means

GPLoad throws this when generating a control file in 'update' (or merge) mode but no update columns were configured. UPDATE operations require UPDATE_COLUMNS to know which fields to set; without them the generated gpload control file would be invalid. It fails fast instead of producing a broken control file.

Solutions

1. In the GPLoad step dialog, populate the Update Columns table for the chosen load action.
2. Switch load action to insert/append if updating is not actually required.
3. Recheck field mappings after upstream schema changes and reselect update columns.
4. When configuring GPLoadMeta in code, set the update column list before invoking the step.

Example fix

// before
meta.setLoadAction("UPDATE"); // update columns not set -> KettleException
// after
meta.setLoadAction("UPDATE");
meta.setUpdateColumn("name");
meta.setUpdateColumn("amount");

if ((meta.getLoadAction().equalsIgnoreCase("UPDATE") || meta.getLoadAction().equalsIgnoreCase("MERGE")) &&
    !meta.hasUpdateColumn()) {
  throw new IllegalArgumentException("Update action requires at least one update column");
}

try {
  step.createControlFile(meta);
} catch (KettleException e) {
  if (e.getMessage().contains("UpdateColumnsNeeded")) { /* add update columns to meta */ }
  else throw e;
}

When it happens

Trigger: getControlFileContents is called (via createControlFile during processRow or testYAMLContents in the dialog) with updateColumn == null or meta.hasUpdateColumn() == false while a mode requiring update columns is selected.

Common situations: User picks 'Update' load action but leaves the update column mapping empty; step configuration migrated from append mode; upstream fields renamed so the configured update column mapping was dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• GPload.Exception.DataFileMissing
• GPload.Exception.DelimiterMissing
• GPLoad.Exception.NoControlFileSpecified
• exceptionMessage
• GPLoad.Exception.MatchColumnsNeeded

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

Appendix: source

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

    String loadAction = meta.getLoadAction();

    // match and update column verification
    if ( loadAction.equalsIgnoreCase( GPLoadMeta.ACTION_MERGE )
        || loadAction.equalsIgnoreCase( GPLoadMeta.ACTION_UPDATE ) ) {

      // throw an exception if we don't have match columns
      if ( matchColumn == null ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.MatchColumnsNeeded" ) );
      }

      if ( !meta.hasMatchColumn() ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.MatchColumnsNeeded" ) );
      }

      // throw an exception if we don't have any update columns
      if ( updateColumn == null ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.UpdateColumnsNeeded" ) );
      }

      if ( !meta.hasUpdateColumn() ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.UpdateColumnsNeeded" ) );
      }
    }

    // data file validation
    String dataFilename = meta.getDataFile();
    if ( !Utils.isEmpty( dataFilename ) ) {
      dataFilename = environmentSubstitute( dataFilename ).trim();
    }
    if ( Utils.isEmpty( dataFilename ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPload.Exception.DataFileMissing" ) );
    }

    // delimiter validation
    String delimiter = meta.getDelimiter();

View on GitHub (pinned to f3058517a1)