pentaho/pentaho-kettle · error · KettleException

GPload.Exception.DataFileMissing

Error message

GPload.Exception.DataFileMissing

What it means

GPLoad validates the data file location before building the control file's DATA_FILE section. If the configured data file is empty (or empty after environment-variable substitution and trimming), the control file cannot point gpload at any data, so a KettleException is thrown.

Solutions

1. Set the data file path in the GPLoad step dialog.
2. Ensure referenced environment variables (e.g. ${DATA_FILE}) are defined at execution time in kettle.properties or the job configuration.
3. Verify the value has no whitespace-only content after variable substitution.
4. Configure the data file programmatically via meta.setDataFile(...) before running the transformation.

Example fix

// before
meta.setDataFile("${DATA_FILE}"); // env var undefined -> empty -> throws
// after
// define DATA_FILE in kettle.properties, or:
meta.setDataFile("/data/loading/table_input.dat");

String dataFile = meta.getDataFile() == null ? null : meta.getDataFile().trim();
if (dataFile == null || dataFile.isEmpty()) {
  throw new IllegalArgumentException("Data file must be set for GPLoad");
}

try {
  step.createControlFile(meta);
} catch (KettleException e) {
  if (e.getMessage().contains("DataFileMissing")) { /* set data file or fix env vars */ }
  else throw e;
}

When it happens

Trigger: getControlFileContents called (via createControlFile in processRow or testYAMLContents) while meta.getDataFile() is null/empty, or resolves to empty after environmentSubstitute().trim().

Common situations: User left the data-file field blank; an environment variable like ${DATA_FILE} is undefined so substitution yields an empty string; data file previously set was cleared during a metadata copy.

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

• GPLoad.Exception.NoControlFileSpecified
• 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/203762fbb3c5ba37. Report an issue: GitHub.

Appendix: source

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

      }

      // 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();
    if ( !Utils.isEmpty( delimiter ) ) {
      delimiter = environmentSubstitute( delimiter ).trim();
    }
    if ( Utils.isEmpty( delimiter ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPload.Exception.DelimiterMissing" ) );
    }

    // Now we start building the contents
    StringBuffer contents = new StringBuffer( 1000 );

    // Source: GP Admin Guide 3.3.6, page 635:
    contents.append( GPLoad.GPLOAD_YAML_VERSION ).append( Const.CR );
    contents.append( "DATABASE: " );
    contents.append( environmentSubstitute( databaseMeta.getDatabaseName() ) );

View on GitHub (pinned to f3058517a1)