pentaho/pentaho-kettle · critical · KettleException

Error while setup

Error message

Error while setup: ${command}

What it means

startFastLoad spawns the external fastload command via Runtime/ProcessBuilder; any Exception thrown while starting the process or wiring its stdin/stdout/stderr streams is wrapped as 'Error while setup: <command>'. The chained cause is the real problem (typically the fastload executable not being found on PATH).

Solutions

1. Install Teradata Tools & Utilities (TTU) or verify the fastload executable exists: which fastload (or full configured path).
2. Add fastload's directory to PATH for the user running Pentaho/Kettle, or configure the full absolute path to the binary.
3. Read the chained cause in the KettleException log to confirm the root error (usually 'Cannot run program ...: No such file or directory').
4. Verify the TeraFast step's fastload client configuration (if a path variable is used, confirm it resolves).
5. Ensure the Kettle service user has execute permission on the fastload binary.

Example fix

// before
Runtime.getRuntime().exec( command ); // fails with no diagnostics if fastload is off PATH
// after
File exe = new File( resolveFileName( meta.getFastloadPath() ) );
if ( !exe.canExecute() ) {
  throw new KettleException( "fastload executable not found at: " + exe.getAbsolutePath() ); // fail early with actionable message
}
Process process = Runtime.getRuntime().exec( command );

// Run before executing the transformation
String cmd = fastloadCommandOrPath;
Process probe = Runtime.getRuntime().exec( new String[]{ "which", cmd.contains( "/" ) ? new File( cmd ).getName() : cmd } );
int rc = probe.waitFor();
if ( rc != 0 || !new File( cmd ).canExecute() && cmd.contains( "/" ) ) {
  throw new IllegalStateException( "fastload executable not found on PATH or at: " + cmd
    + "; install Teradata TTU or set the full absolute path" );
}

try {
  this.process = Runtime.getRuntime().exec( command );
} catch ( IOException e ) {
  throw new KettleException( "Error while setup: " + command
    + " — verify the fastload executable exists, is on PATH, and is executable by this user", e );
}

When it happens

Trigger: execute() -> startFastLoad(): the fastload binary path is wrong or not on PATH (IOException from Runtime.exec), the SecurityManager denies execution, or an exception occurs acquiring process.getInputStream()/getOutputStream() during stream wiring.

Common situations: Teradata Utilities/TTU not installed on the Kettle host; fastload installed but not in PATH of the user running the transformation; wrong absolute path configured; running on a host/OS where the client tools are absent (e.g. Windows vs Linux agent).

Related errors

• Cannot open control file
• Cannot open data file
• Cannot pipe content of control file to fastload
• TeraFast.Exception.TypeNotSupported
• Error defining data file!

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

Appendix: source

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

  /**
   * Start fastload command line tool and initialize streams.
   *
   * @throws KettleException
   *           ...
   */
  private void startFastLoad() throws KettleException {
    final String command = this.createCommandLine();
    this.logBasic( "About to execute: " + command );
    try {
      this.process = Runtime.getRuntime().exec( command );
      new Thread( new ConfigurableStreamLogger(
        getLogChannel(), this.process.getErrorStream(), LogLevel.ERROR, "ERROR" ) ).start();
      new Thread( new ConfigurableStreamLogger(
        getLogChannel(), this.process.getInputStream(), LogLevel.DETAILED, "OUTPUT" ) ).start();
      this.fastload = this.process.getOutputStream();
    } catch ( Exception e ) {
      throw new KettleException( "Error while setup: " + command, e );
    }
  }

  /**
   * Invoke loading with control file.
   *
   * @throws KettleException
   *           ...
   */
  private void invokeLoadingControlFile() throws KettleException {
    File controlFile = null;
    final InputStream control;
    final String controlContent;
    try {
      controlFile = new File( resolveFileName( this.meta.getControlFile().getValue() ) );
      control = FileUtils.openInputStream( controlFile );
      controlContent = environmentSubstitute( FileUtils.readFileToString( controlFile ) );
    } catch ( IOException e ) {

View on GitHub (pinned to f3058517a1)