pentaho/pentaho-kettle · error · KettleException

GPLoad.Exception.NoControlFileSpecified

Error message

GPLoad.Exception.NoControlFileSpecified

What it means

createControlFile first validates that the control file name is configured, since gpload must be told which control file to run. If meta.getControlFile() is empty, a KettleException with GPLoad.Exception.NoControlFileSpecified is thrown before any file I/O.

Solutions

1. Set the control file path in the GPLoad step dialog (e.g. /tmp/load.ctl).
2. Provide the path via an environment variable and ensure it is defined at runtime.
3. Set meta.setControlFile("/path/to/load.ctl") programmatically before running the transformation.
4. If the path should be generated dynamically, compute it in a preceding step and pass it as a variable.

Example fix

// before
meta.setControlFile(""); // throws GPLoad.Exception.NoControlFileSpecified
// after
meta.setControlFile("/tmp/gpload_control.ctl");

String ctl = meta.getControlFile();
if (ctl == null || ctl.trim().isEmpty()) {
  throw new IllegalArgumentException("Control file must be specified");
}

try {
  step.createControlFile(meta);
} catch (KettleException e) {
  if (e.getMessage().contains("NoControlFileSpecified")) { /* set control file path */ }
  else throw e;
}

When it happens

Trigger: processRow -> createControlFile(meta) with meta.getControlFile() returning null or an empty string.

Common situations: Control-file field left blank in the step dialog; metadata exported/imported without the field; step cloned from a template where the path was cleared.

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

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

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

Appendix: source

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

              updateCondition ).append( GPLoad.DOUBLE_QUOTE ).append( Const.CR );
        }
      }
    }

    return contents.toString();
  }

  /**
   * Create a control file.
   *
   * @param filename
   * @param meta
   * @throws KettleException
   */
  public void createControlFile( GPLoadMeta meta ) throws KettleException {
    String filename = meta.getControlFile();
    if ( Utils.isEmpty( filename ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.NoControlFileSpecified" ) );
    } else {
      filename = environmentSubstitute( filename ).trim();
      if ( Utils.isEmpty( filename ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.NoControlFileSpecified" ) );
      }
    }

    File controlFile = new File( filename );
    FileWriter fw = null;

    try {
      controlFile.createNewFile();
      fw = new FileWriter( controlFile );
      fw.write( getControlFileContents( meta, getInputRowMeta() ) );
    } catch ( IOException ex ) {
      throw new KettleException( ex.getMessage(), ex );
    } finally {
      try {

View on GitHub (pinned to f3058517a1)