pentaho/pentaho-kettle · error · KettleException

Error retrieving fastload application string

Error message

Error retrieving fastload application string

What it means

After confirming the fastload path is set, createCommandLine resolves the executable via KettleVFS (with environment substitution) to obtain its real filename. Any failure in that resolution — filesystem errors, VFS problems, bad URIs — is wrapped in a KettleException with message 'Error retrieving fastload application string', with the original exception as the cause.

Solutions

1. Check the 'cause' of this exception in the log — it names the actual VFS/IO problem.
2. Fix the Fastload path in the step dialog so it is a plain, valid absolute filesystem path (e.g. /usr/bin/fastload or C:\...\fastload.exe).
3. Resolve any embedded ${VARIABLE} to ensure environment substitution produces a valid path.
4. Verify the path exists and is readable by the user running Pentaho/Kettle.
5. If a shared/network path is used, confirm the mount or share is available from the executing host.

Example fix

// before
Fastload path: ${TLA_HOME}/bin/fastload  // TLB_HOME never set -> VFS gets garbage
// after
Fastload path: /opt/teradata/client/bin/fastload  // or define TLB_HOME in kettle.properties

String raw = meta.getFastloadPath().getValue();
String resolved = transMeta.environmentSubstitute(raw);
java.io.File f = new java.io.File(resolved);
if (!f.exists() || !f.canExecute()) {
  throw new IllegalStateException("Fastload executable not found or not executable: " + resolved);
}

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("Error retrieving fastload application string")) {
    logError("Fastload path could not be resolved via VFS; cause: " + e.getCause());
  } else {
    throw e;
  }
}

When it happens

Trigger: KettleVFS.getFileObject(environmentSubstitute(fastloadPath)) throws or KettleVFS.getFilename(fileObject) fails, e.g. the configured path is not a valid VFS URI, contains unresolved/illegal characters, or the file cannot be accessed.

Common situations: The fastload path contains unexpanded variables or special characters that break VFS resolution; the configured location points to a non-existent drive/share on Windows; a malformed file: URL was pasted into the dialog; VFS provider issues after a Pentaho upgrade.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Error retrieving logfile string
• Cannot open control file
• Cannot open data file
• Cannot pipe content of control file to fastload
• Error defining data file!

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

Appendix: source

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

   *
   * @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 " );
        builder.append( "\"" + KettleVFS.getFilename( fileObject ) + "\"" );
      } catch ( Exception e ) {
        throw new KettleException( "Error retrieving logfile string", e );
      }
    }
    return builder.toString();
  }

  protected void verifyDatabaseConnection() throws KettleException {
    // Confirming Database Connection is defined.

View on GitHub (pinned to f3058517a1)