pentaho/pentaho-kettle · error · KettleException

Error defining data file!

Error message

Error defining data file!

What it means

TeraFast (Teradata fastload bulk loader step) wraps any failure while asking the FastloadControlBuilder to emit the fastload DEFINE directive for the data file. The builder.define() call maps the incoming row fields to the target table columns and the local data file; any exception there (bad field metadata, missing/unresolvable data file name, builder state issues) is rethrown as a KettleException.

Solutions

1. Verify the step's field mapping (required fields vs table field list) matches the actual target table in Teradata
2. Check that the data file path resolves to a writable, valid location (environment variables resolve)
3. Inspect the wrapped cause (ex) in the KettleException stack trace for the root error from FastloadControlBuilder
4. Reopen and re-save the step dialog to regenerate metadata after table changes

Example fix

// before
builder.define( meta.getRequiredFields( transMeta ), meta.getTableFieldList(), resolveFileName( meta.getDataFile().getValue() ) );
// after
String dataFile = environmentSubstitute( meta.getDataFile().getValue() );
if ( dataFile == null || dataFile.trim().isEmpty() ) {
  throw new KettleException( "Data file path is not set" );
}
builder.define( meta.getRequiredFields( transMeta ), meta.getTableFieldList(), dataFile );

// before executing the transformation
TeraFastMeta meta = ...;
if ( meta.getDbMeta() == null ) throw new KettleException( "No DB connection set" );
if ( meta.getDataFile() == null || meta.getDataFile().getValue() == null ) throw new KettleException( "No data file set" );
RowMetaInterface req = meta.getRequiredFields( transMeta );
if ( req == null || req.size() == 0 ) throw new KettleException( "No required fields resolved for target table" );

boolean isUsable( TeraFastMeta m ) {
  return m != null && m.getDbMeta() != null && m.getDataFile() != null
    && m.getDataFile().getValue() != null && m.getTargetTable() != null;
}

try {
  step.run();
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "Error defining data file" ) ) {
    logError( "Fastload DEFINE failed: " + e.getCause(), e ); // inspect cause
  } else { throw e; }
}

When it happens

Trigger: invokeLoadingCommand() calls builder.define(meta.getRequiredFields(transMeta), meta.getTableFieldList(), resolveFileName(meta.getDataFile().getValue())) and it throws — e.g. requiredFields lookup returned metadata that does not match the tableFieldList, the data filename cannot be resolved, or the builder is in an invalid state.

Common situations: Target table was altered after the step was configured so required fields no longer align; data file path contains variables that do not resolve; fastload utility misconfigured; step metadata serialized from an older PDI version.

Related errors

• Cannot open control file
• Cannot open data file
• Cannot pipe content of control file to fastload
• Error while execution control command
• Error while setup

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

Appendix: source

Thrown at plugins/terafast-bulk-loader/impl/src/main/java/org/pentaho/di/trans/steps/terafastbulkloader/TeraFast.java:398

  /**
   * Invoke loading with loading commands.
   *
   * @throws KettleException
   *           ...
   */
  private void invokeLoadingCommand() throws KettleException {
    final FastloadControlBuilder builder = new FastloadControlBuilder();
    builder.setSessions( this.meta.getSessions().getValue() );
    builder.setErrorLimit( this.meta.getErrorLimit().getValue() );
    builder.logon( this.meta.getDbMeta().getHostname(), this.meta.getDbMeta().getUsername(), this.meta
      .getDbMeta().getPassword() );
    builder.setRecordFormat( FastloadControlBuilder.RECORD_VARTEXT );
    try {
      builder.define(
        this.meta.getRequiredFields( this.getTransMeta() ), meta.getTableFieldList(), resolveFileName( this.meta
          .getDataFile().getValue() ) );
    } catch ( Exception ex ) {
      throw new KettleException( "Error defining data file!", ex );
    }
    builder.show();
    builder.beginLoading( this.meta.getDbMeta().getPreferredSchemaName(), this.meta.getTargetTable().getValue() );

    builder.insert( this.meta.getRequiredFields( this.getTransMeta() ), meta.getTableFieldList(), this.meta
      .getTargetTable().getValue() );
    builder.endLoading();
    builder.logoff();
    final String control = builder.toString();
    try {
      logDetailed( "Control file: " + control );
      IOUtils.write( control, this.fastload );
    } catch ( IOException e ) {
      throw new KettleException( "Error while execution control command [controlCommand=" + control + "]", e );
    } finally {
      IOUtils.closeQuietly( this.fastload );
    }
  }

View on GitHub (pinned to f3058517a1)