pentaho/pentaho-kettle · critical · KettleException

LDAPinput.Exception.ErrorConnecting

LDAPinput.Exception.ErrorConnecting

Error message

LDAPinput.Exception.ErrorConnecting

What it means

Thrown by LdapProtocol.connect() when establishing the LDAP connection via the configured directory context (InitialLdapContext) fails with any Exception. The original message from the JNDI/LDAP layer is embedded, so the real reason (wrong host/port, bad credentials, TLS failure, DNS) is in the cause. The step cannot proceed without a connection to the directory server.

Solutions

  1. Read the cause message: 'Connection refused' = wrong host/port/firewall; 'Invalid credentials' = fix bind DN/password
  2. Test the server with ldapsearch or ldapmodify from the same host to isolate network issues
  3. If using LDAPS, import the server certificate into the JVM truststore or configure the step's trust store (see CustomSocketFactory)
  4. Verify the LDAP URL format, e.g. ldap://host:389 or ldaps://host:636

Example fix

// before (in step dialog)
Host: ldp-server1, Port: 636, Use encryption: yes
// after
Host: ldap-server1.example.com, Port: 636, Use encryption: yes (with server cert in truststore)
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check connectivity before running the transformation
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(host, port), 5000); // host=ldap.example.com, port=636
}

Try / catch

try {
  runTransformation();
} catch (KettleException e) {
  // message contains 'LDAPinput.Exception.ErrorConnecting' + cause message
  log.error("LDAP connect failed: " + e.getCause().getMessage(), e.getCause());
  // route: Connection refused -> host/port; Invalid credentials -> bind DN/password;
  // SSLHandshakeException -> import server certificate
}

Prevention

When it happens

Trigger: new InitialLdapContext(env, null) inside connect() throws: invalid LDAP URL/host/port, authentication bind failure, SSL/TLS handshake error, or naming exception (host not found).

Common situations: Typo in hostname or port; LDAP server firewall blocks 389/636; wrong bind DN or password; using ldaps:// without importing the server certificate into the truststore; DNS resolution failure.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at plugins/ldap/impl/src/main/java/org/pentaho/di/trans/steps/ldapinput/LdapProtocol.java:155

  }

  public final void connect( String username, String password ) throws KettleException {
    Hashtable<String, String> env = new Hashtable<String, String>();
    setupEnvironment( env, username, password );
    try {
      /* Establish LDAP association */
      doConnect( username, password );

      if ( log.isBasic() ) {
        log.logBasic( BaseMessages.getString( PKG, "LDAPInput.Log.ConnectedToServer", hostname, Const.NVL(
          username, "" ) ) );
      }
      if ( log.isDetailed() ) {
        log.logDetailed( BaseMessages.getString( PKG, "LDAPInput.ClassUsed.Message", ctx.getClass().getName() ) );
      }

    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "LDAPinput.Exception.ErrorConnecting", e
        .getMessage() ), e );
    }
  }

  public void close() throws KettleException {
    if ( ctx != null ) {
      try {
        ctx.close();
        if ( log.isBasic() ) {
          log.logBasic( BaseMessages.getString( PKG, "LDAPInput.log.Disconnection.Done" ) );
        }
      } catch ( Exception e ) {
        log.logError( BaseMessages.getString( PKG, "LDAPInput.Exception.ErrorDisconecting", e.toString() ) );
        log.logError( Const.getStackTracker( e ) );
      } finally {
        ctx = null;
      }
    }

View on GitHub (pinned to f3058517a1)