pentaho/pentaho-kettle · error · KettleJobException

Proxy server name must be set and server port must be…

Error message

Proxy server name must be set and server port must be greater than zero.

What it means

SFTPClient.setProxy validates proxy configuration before building a JSch Proxy. If host is empty or port parses (Const.toInt) to 0, it throws KettleJobException with this message. It is a configuration guard — the proxy was never contacted.

Solutions

Set a valid proxy hostname and a numeric port > 0 in the job entry proxy settings
Check that variables used in host/port resolve at runtime (${VAR} left unexpanded is empty/invalid)
Verify proxy type matches the actual proxy (HTTP vs SOCKS5)
Temporarily hardcode host/port to confirm the variable resolution is the culprit

Example fix

// before
sftpClient.setProxy(proxyHost, proxyPort, user, pass, PROXY_TYPE_HTTP);
// after
if (proxyHost != null && !proxyHost.isEmpty() && Const.toInt(proxyPort, 0) > 0) {
  sftpClient.setProxy(proxyHost, proxyPort, user, pass, PROXY_TYPE_HTTP);
} else {
  throw new KettleJobException("Invalid proxy config: host=" + proxyHost + " port=" + proxyPort);
}

Defensive patterns

Strategy: validation

Validate before calling

if (Utils.isEmpty(proxyHost) || Const.toInt(proxyPort, 0) <= 0) {
  throw new KettleJobException("Proxy host/port invalid: host=" + proxyHost + " port=" + proxyPort);
}
sftpClient.setProxy(proxyHost, proxyPort, proxyUser, proxyPass, proxyType);

Try / catch

try {
  sftpClient.setProxy(host, port, user, pass, proxyType);
} catch (KettleJobException e) {
  logError("Proxy configuration invalid — check host and port variables resolved correctly", e);
}

Prevention

Never leave host empty or port 0/blank when 'use proxy' is enabled
Verify ${VARIABLES} in proxy fields resolve at runtime (log resolved values)
Validate the port is numeric and > 0 before invoking
Disable the proxy option entirely if no proxy is intended

When it happens

Trigger: setProxy(host, port, user, pass, proxyType) called with null/empty host, or a port string that is non-numeric/blank/"0" so Const.toInt defaults to 0. Called from the SFTP job entry execute() when proxy settings are enabled.

Common situations: Proxy port left blank or containing a variable that did not resolve; port typed as 0; hostname field cleared while 'use proxy' checkbox still enabled; environment-specific variables missing at runtime.

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/6aef8d327f1efe30. Report an issue: GitHub.

Appendix: source

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

        return false;
      }

      if ( ( attrs.getFlags() & SftpATTRS.SSH_FILEXFER_ATTR_PERMISSIONS ) == 0 ) {
        throw new KettleJobException( "Unknown permissions error" );
      }

      retval = attrs.isDir();
    } catch ( Exception e ) {
      // Folder can not be found!
    }
    return retval;
  }

  public void setProxy( String host, String port, String user, String pass, String proxyType )
    throws KettleJobException {

    if ( Utils.isEmpty( host ) || Const.toInt( port, 0 ) == 0 ) {
      throw new KettleJobException( "Proxy server name must be set and server port must be greater than zero." );
    }
    Proxy proxy = null;
    String proxyhost = host + ":" + port;

    if ( proxyType.equals( PROXY_TYPE_HTTP ) ) {
      proxy = new ProxyHTTP( proxyhost );
      if ( !Utils.isEmpty( user ) ) {
        ( (ProxyHTTP) proxy ).setUserPasswd( user, pass );
      }
    } else if ( proxyType.equals( PROXY_TYPE_SOCKS5 ) ) {
      proxy = new ProxySOCKS5( proxyhost );
      if ( !Utils.isEmpty( user ) ) {
        ( (ProxySOCKS5) proxy ).setUserPasswd( user, pass );
      }
    }
    session.setProxy( proxy );
  }

View on GitHub (pinned to f3058517a1)