SonarSource/sonarqube · error · LdapException

Unable to open LDAP connection

Error message

Unable to open LDAP connection

What it means

testConnection attempts createBindContext() and, if the bind fails with a NamingException, logs 'Test LDAP connection: FAIL' and rethrows as LdapException 'Unable to open LDAP connection' with the original exception as cause. It is the health-check failure signal for an LDAP endpoint — the library could not establish/bind a directory context.

Source

Thrown at server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapContextFactory.java:230

  public boolean isGssapi() {
    return AUTH_METHOD_GSSAPI.equals(authentication);
  }

  /**
   * Tests connection.
   *
   * @throws LdapException if unable to open connection
   */
  public void testConnection() {
    if (StringUtils.isBlank(username) && isSasl()) {
      throw new IllegalArgumentException("When using SASL - property ldap.bindDn is required");
    }
    try {
      createBindContext();
      LOG.info("Test LDAP connection on {}: OK", providerUrl);
    } catch (NamingException e) {
      LOG.info("Test LDAP connection: FAIL");
      throw new LdapException("Unable to open LDAP connection", e);
    }
  }

  public String getProviderUrl() {
    return providerUrl;
  }

  public String getReferral() {
    return referral;
  }

  private static String getReferralsMode(org.sonar.api.config.Configuration config, String followReferralsSettingKey) {
    // By default follow referrals
    return config.getBoolean(followReferralsSettingKey).orElse(true) ? REFERRALS_FOLLOW_MODE : REFERRALS_IGNORE_MODE;
  }

  @Override
  public String toString() {

View on GitHub (pinned to 184c821202)

Solutions

1. Inspect the cause (NamingException) logged at info/debug to distinguish connectivity vs authentication vs TLS failure.
2. Verify network reachability: telnet/nc to the ldap host and port.
3. Validate bind credentials with ldapsearch using the same bindDn/bindPassword.
4. For ldaps://, import the server certificate into the JVM truststore.

Example fix

// before: wrong port / unreachable
sonar.authenticator.ldap.url: ldap://ldap.example.com:10389
// after: correct endpoint
sonar.authenticator.ldap.url: ldap://ldap.example.com:389

// pre-flight connectivity check before triggering LDAP operations
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(host, port), 3000); // host/port parsed from ldap.url
}

try {
  contextFactory.testConnection();
} catch (LdapException e) {
  if (e.getCause() instanceof CommunicationException) {
    // retry with backoff; likely transient network issue
  } else if (e.getCause() instanceof AuthenticationException) {
    // fix bindDn/bindPassword — do not retry blindly
  }
}

When it happens

Trigger: Calling testConnection when createBindContext() throws — wrong ldap.url host/port, network unreachable, bind credentials rejected (AuthenticationException), or TLS handshake failure on ldaps://.

Common situations: LDAP server down or firewall blocking 389/636; expired bind password; TLS certificate not in truststore; DNS resolution failure for the LDAP host; invalid URL scheme in ldap.url.

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

• Unable to retrieve details for user <username> in <serverKey
• SonarQube was not able to retrieve resources from external s
• %s for request [%s]: [%s]
• Unable to contact Bitbucket Cloud servers
• Error returned by Bitbucket Cloud

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/84b2d87b58d27145. Report an issue: GitHub.