pentaho/pentaho-kettle · error · KettleJobException

For a SFTP connection server name and username must be set…

Error message

For a SFTP connection server name and username must be set and server port must be greater than zero.

What it means

The SFTPClient constructor validates connection parameters before connecting: a non-null server IP, a port greater than zero, and a non-empty username are all mandatory. If any is missing it throws this KettleJobException with a literal message describing the requirements.

Solutions

Fill in the SFTP job entry's server name, port, and username fields.
Resolve the host with InetAddress.getByName(host) before constructing SFTPClient and check it is non-null.
Default the port to 22 when unset and validate port is an integer > 0.
Trim the username and reject empty strings before instantiating.

Example fix

// before
SFTPClient c = new SFTPClient(bowl, null, 0, "", null, null);
// after
InetAddress ip = InetAddress.getByName("sftp.example.com");
if (ip == null || port <= 0 || user == null || user.isEmpty()) throw new IllegalArgumentException("bad sftp config");
SFTPClient c = new SFTPClient(bowl, ip, port, user, null, null);

Defensive patterns

Strategy: validation

Validate before calling

InetAddress ip = InetAddress.getByName(host); // throws UnknownHostException early
if (ip == null || serverPort <= 0 || userName == null || userName.trim().isEmpty()) {
  throw new IllegalArgumentException("SFTP requires server, port>0 and username");
}

Try / catch

try {
  new SFTPClient(bowl, ip, port, user, key, passphrase);
} catch (KettleJobException e) {
  logError("SFTP config invalid: " + e.getMessage());
}

Prevention

Require host, port, and username fields before saving the job entry.
Default port to 22 and clamp to 1-65535.
Trim and validate the username at design time.

When it happens

Trigger: new SFTPClient(bowl, null, port, user, ...) with serverIP null; port <= 0; or userName null or empty string.

Common situations: SFTP job entry fields not filled in (server name empty, port left 0 or -1); variables resolving to empty strings at runtime; programmatic use of SFTPClient without resolving the hostname to an InetAddress.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/entries/sftp/SFTPClient.java:137

   * @param bowl
   *          Bowl providing context for File operations
   * @param serverIP
   *          IP address of remote server
   * @param serverPort
   *          port of remote server
   * @param userName
   *          username of remote server
   * @param privateKeyFilename
   *          filename of private key
   * @param passPhrase
   *          passphrase
   * @throws KettleJobException
   */
  public SFTPClient( Bowl bowl, InetAddress serverIP, int serverPort, String userName, String privateKeyFilename,
    String passPhrase ) throws KettleJobException {

    if ( serverIP == null || serverPort <= 0 || userName == null || userName.equals( "" ) ) {
      throw new KettleJobException(
        "For a SFTP connection server name and username must be set and server port must be greater than zero." );
    }

    this.serverIP = serverIP;
    this.serverPort = serverPort;
    this.userName = userName;
    this.bowl = bowl;

    JSch jsch = createJSch();
    try {
      if ( !Utils.isEmpty( privateKeyFilename ) ) {
        // We need to use private key authentication
        this.prvkey = privateKeyFilename;

        byte[] passPhraseBytes;
        if ( !Utils.isEmpty( passPhrase ) ) {
          // Set passphrase
          this.passphrase = passPhrase;

View on GitHub (pinned to f3058517a1)