SonarSource/sonarqube · critical · LdapException

LDAP realm failed to start:

Error message

LDAP realm failed to start: 

What it means

testConnections iterates all configured LDAP servers calling contextFactory.testConnection(); any RuntimeException (including 'Unable to open LDAP connection') is rethrown as 'LDAP realm failed to start: <cause message>' unless ignoreStartupFailure is set, in which case it is only logged. It signals the SonarQube LDAP realm could not initialize against at least one server.

Source

Thrown at server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapRealm.java:85

    LdapSettingsManager settingsManager) {
    Map<String, LdapGroupMapping> groupMappings = settingsManager.getGroupMappings();
    if (!groupMappings.isEmpty()) {
      return new DefaultLdapGroupsProvider(contextFactories, userMappings, groupMappings);
    } else {
      return null;
    }
  }

  private static void testConnections(Map<String, LdapContextFactory> contextFactories, boolean ignoreStartupFailure) {
    try {
      for (LdapContextFactory contextFactory : contextFactories.values()) {
        contextFactory.testConnection();
      }
    } catch (RuntimeException e) {
      if (ignoreStartupFailure) {
        LOG.error("IGNORED - LDAP realm failed to start: " + e.getMessage());
      } else {
        throw new LdapException("LDAP realm failed to start: " + e.getMessage(), e);
      }
    }
  }

  @CheckForNull
  public LdapAuthenticator getAuthenticator() {
    return authenticator;
  }

  @CheckForNull
  public LdapUsersProvider getUsersProvider() {
    return usersProvider;
  }

  @CheckForNull
  public LdapGroupsProvider getGroupsProvider() {
    return groupsProvider;
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Fix the underlying connection problem indicated by the cause message (check ldap.url, bindDn, bindPassword per server).
2. Temporarily set sonar.authenticator.ldap.ignoreStartupFailure=true so SonarQube can start while LDAP issues are resolved (logins will fall back to local).
3. Check LDAP server availability and firewall rules before restarting SonarQube.
4. Review the full stack trace in sonar.log for which server key failed.

Example fix

// before: startup hard-fails when LDAP is down
// (no ignore setting)
// after: tolerate startup failure
sonar.authenticator.ldap.ignoreStartupFailure: true

// verify every configured server is reachable before restart
for (String key : serverKeys) {
  String url = config.get("sonar.authenticator.ldap." + key + ".url");
  assertReachable(url); // socket connect to host:port
}

try {
  startRealm();
} catch (LdapException e) {
  LOG.error("LDAP realm failed to start: {} — falling back to local auth", e.getMessage());
  enableLocalAuthenticationOnly();
}

When it happens

Trigger: SonarQube startup with the LDAP plugin when any server's testConnection() throws — bad ldap.url, rejected bind, or the SASL bindDn validation. Behavior depends on the sonar.authenticator.ldap.ignoreStartupFailure setting.

Common situations: SonarQube rebooted while the LDAP server is down; config change (wrong bindPassword) introduced at upgrade; multi-server setups where one of several servers is unreachable blocks startup.

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

• Github configuration is not complete. Please check your conf
• Configuration is not complete : %s
• Callback not supported
• Unable to retrieve groups for user %s in server with key <%s
• Unable to retrieve details for user %s: No user or group map

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