What causes "Fastload path not set" in pentaho/pentaho-kettle?

Open the Terafast Bulk Loader step dialog and set the Fastload executable path (e.g. /opt/teradata/client/15.10/bin/fastload).

pentaho/pentaho-kettle · error · KettleException

Fastload path not set

Error message

Fastload path not set

What it means

TeraFast.createCommandLine builds the fastload command line but first checks that the Fastload executable path configured in the step metadata is non-blank. If meta.getFastloadPath().getValue() is empty or null, it throws 'Fastload path not set' because the tool cannot construct a valid fastload command without the executable location.

Solutions

Open the Terafast Bulk Loader step dialog and set the Fastload executable path (e.g. /opt/teradata/client/15.10/bin/fastload).
If the path uses an environment variable, confirm it is defined and non-empty at runtime (kettle.properties or Set Variables step).
Verify the value actually reaches the metadata: check the saved ktr XML for the fastload path property.

Example fix

// before (dialog config)
Fastload path: (empty)
// after
Fastload path: /opt/teradata/client/16.20/bin/fastload

Defensive patterns

Strategy: validation

Validate before calling

String fastloadPath = meta.getFastloadPath() == null ? null : meta.getFastloadPath().getValue();
if (fastloadPath == null || fastloadPath.trim().isEmpty()) {
  throw new IllegalStateException("Fastload path must be set before running the Terafast Bulk Loader step");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if ("Fastload path not set".equals(e.getUnwrappedMessage())) {
    logError("Configure the Fastload executable path in the Terafast Bulk Loader step");
  } else {
    throw e;
  }
}

Prevention

Fill in the absolute path of the fastload binary in every environment where the transformation runs.
Use environment variables consistently and ensure they are defined on all execution hosts.
Add a pre-flight check (e.g. Files.exists on the resolved path) before deploying transformations that use this step.
Document required local tooling (Teradata client with fastload) for the operations team.

When it happens

Trigger: The step's 'Fastload path' field is left empty in the dialog (or the underlying variable/parameter resolves to blank), and command() invokes createCommandLine() during step initialization.

Common situations: A developer forgot to fill in the path to the `fastload` binary when configuring the Terafast Bulk Loader; an environment variable used for the path is undefined at runtime; a transformation was migrated between machines where the path field was cleared.

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

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

Appendix: source

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

   * @param trans
   *          the trans.
   */
  public TeraFast( final StepMeta stepMeta, final StepDataInterface stepDataInterface, final int copyNr,
    final TransMeta transMeta, final Trans trans ) {
    super( stepMeta, stepDataInterface, copyNr, transMeta, trans );
  }

  /**
   * Create the command line for a fastload process depending on the meta information supplied.
   *
   * @return The string to execute.
   *
   * @throws KettleException
   *           Upon any exception
   */
  public String createCommandLine() throws KettleException {
    if ( StringUtils.isBlank( this.meta.getFastloadPath().getValue() ) ) {
      throw new KettleException( "Fastload path not set" );
    }
    final StringBuilder builder = new StringBuilder();
    try {
      final FileObject fileObject =
        KettleVFS.getInstance( getTransMeta().getBowl() )
          .getFileObject( environmentSubstitute( this.meta.getFastloadPath().getValue() ) );
      final String fastloadExec = KettleVFS.getFilename( fileObject );
      builder.append( fastloadExec );
    } catch ( Exception e ) {
      throw new KettleException( "Error retrieving fastload application string", e );
    }
    // Add log error log, if set.
    if ( StringUtils.isNotBlank( this.meta.getLogFile().getValue() ) ) {
      try {
        FileObject fileObject =
          KettleVFS.getInstance( getTransMeta().getBowl() )
            .getFileObject( environmentSubstitute( this.meta.getLogFile().getValue() ) );
        builder.append( " -e " );

View on GitHub (pinned to f3058517a1)