{"record":{"id":"01d11b7dba678b50","repo":"pentaho/pentaho-kettle","slug":"gpload-exception-updatecolumnsneeded","errorCode":null,"errorMessage":"GPLoad.Exception.UpdateColumnsNeeded","messagePattern":"GPLoad\\.Exception\\.UpdateColumnsNeeded","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/gpload/core/src/main/java/org/pentaho/di/trans/steps/gpload/GPLoad.java","lineNumber":188,"sourceCode":"\n    String loadAction = meta.getLoadAction();\n\n    // match and update column verification\n    if ( loadAction.equalsIgnoreCase( GPLoadMeta.ACTION_MERGE )\n        || loadAction.equalsIgnoreCase( GPLoadMeta.ACTION_UPDATE ) ) {\n\n      // throw an exception if we don't have match columns\n      if ( matchColumn == null ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"GPLoad.Exception.MatchColumnsNeeded\" ) );\n      }\n\n      if ( !meta.hasMatchColumn() ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"GPLoad.Exception.MatchColumnsNeeded\" ) );\n      }\n\n      // throw an exception if we don't have any update columns\n      if ( updateColumn == null ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"GPLoad.Exception.UpdateColumnsNeeded\" ) );\n      }\n\n      if ( !meta.hasUpdateColumn() ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"GPLoad.Exception.UpdateColumnsNeeded\" ) );\n      }\n    }\n\n    // data file validation\n    String dataFilename = meta.getDataFile();\n    if ( !Utils.isEmpty( dataFilename ) ) {\n      dataFilename = environmentSubstitute( dataFilename ).trim();\n    }\n    if ( Utils.isEmpty( dataFilename ) ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"GPload.Exception.DataFileMissing\" ) );\n    }\n\n    // delimiter validation\n    String delimiter = meta.getDelimiter();","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/gpload/core/src/main/java/org/pentaho/di/trans/steps/gpload/GPLoad.java#L170-L206","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["In the GPLoad step dialog, populate the Update Columns table for the chosen load action.","Switch load action to insert/append if updating is not actually required.","Recheck field mappings after upstream schema changes and reselect update columns.","When configuring GPLoadMeta in code, set the update column list before invoking the step."],"exampleFix":"// before\nmeta.setLoadAction(\"UPDATE\"); // update columns not set -> KettleException\n// after\nmeta.setLoadAction(\"UPDATE\");\nmeta.setUpdateColumn(\"name\");\nmeta.setUpdateColumn(\"amount\");","handlingStrategy":"validation","validationCode":"if ((meta.getLoadAction().equalsIgnoreCase(\"UPDATE\") || meta.getLoadAction().equalsIgnoreCase(\"MERGE\")) &&\n    !meta.hasUpdateColumn()) {\n  throw new IllegalArgumentException(\"Update action requires at least one update column\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  step.createControlFile(meta);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"UpdateColumnsNeeded\")) { /* add update columns to meta */ }\n  else throw e;\n}","preventionTips":["Map update columns in the same dialog session where you choose the Update action.","Run the dialog's YAML test to catch missing mappings early.","Re-check mappings after upstream stream schema changes.","Document required GPLoadMeta fields per load action in team code reviews."],"tags":["kettle","gpload","greenplum","configuration","update"],"backgroundTag":"missing-required-argument","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}