pentaho/pentaho-kettle · error · KettleException

GPLoad.Exception.GPLoadCommandBuild

Error message

GPLoad.Exception.GPLoadCommandBuild

What it means

getPath() wraps any Apache Commons VFS FileSystemException raised while resolving or inspecting the file (or its parent) into a KettleException with key GPLoad.Exception.GPLoadCommandBuild, embedding fsex.getMessage(). It signals the gpload command line could not be built because the filesystem layer failed.

Solutions

  1. Fix the path syntax in the step settings (quote/escape spaces and special characters, especially on Windows).
  2. Check the embedded fsex message in the stack trace to identify the VFS-level cause.
  3. Use a plain local filesystem path if a remote or unusual scheme is failing.
  4. Verify Kettle VFS configuration and that the target filesystem is reachable.

Example fix

// before
String path = "C:\Program Files\gpload\gpload.exe"; // unescaped backslashes/spaces
// after
String path = "C:/PROGRA~1/gpload/gpload.exe"; // or properly escaped path
Defensive patterns

Strategy: try-catch

Validate before calling

String path = "/opt/gp load/gpload";
if (path.matches(".*[^\\w/.:~-].*")) {
  logBasic("Warning: path contains characters that may break VFS: " + path);
}

Try / catch

try {
  execute();
} catch (KettleException ke) {
  Throwable root = ke;
  while (root.getCause() != null) root = root.getCause();
  logError("VFS failure building gpload command: " + root.getMessage(), ke);
  throw ke;
}

Prevention

When it happens

Trigger: KettleVFS.getFileObject() or fileObject.exists()/getParent()/getURL() throws FileSystemException - e.g., an invalid or unsupported URI scheme, malformed path characters, or VFS provider errors.

Common situations: Paths with characters VFS cannot parse (unescaped spaces or symbols, bad Windows paths); unsupported URI scheme; VFS misconfiguration or missing provider; network filesystem unreachable.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

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

      } else { // if the file does not have to exist, the parent, or source folder, does.
        FileObject parentFolder = fileObject.getParent();
        if ( parentFolder.exists() ) {
          return KettleVFS.getFilename( fileObject );
        } else {
          throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.DirectoryDoesNotExist",
              parentFolder.getURL().getPath() ) );
        }

      }

      // if Windows is the OS
      if ( Const.getOS().startsWith( "Windows" ) ) {
        return addQuotes( pathToFile );
      } else {
        return KettleVFS.getFilename( fileObject );
      }
    } catch ( FileSystemException fsex ) {
      throw new KettleException( BaseMessages.getString( PKG, "GPLoad.Exception.GPLoadCommandBuild", fsex.getMessage() ) );
    }
  }

  /**
   * Create the command line for GPLoad depending on the meta information supplied.
   *
   * @param meta
   *          The meta data to create the command line from
   * @param password
   *          Use the real password or not
   *
   * @return The string to execute.
   *
   * @throws KettleException
   *           Upon any exception
   */
  public String createCommandLine( GPLoadMeta meta, boolean password ) throws KettleException {

View on GitHub (pinned to f3058517a1)