{"record":{"id":"378d0d92b3825d0d","repo":"SonarSource/sonarqube","slug":"ldap-realm-failed-to-start","errorCode":null,"errorMessage":"LDAP realm failed to start: ","messagePattern":"LDAP realm failed to start: ","errorType":"exception","errorClass":"LdapException","httpStatus":null,"severity":"critical","filePath":"server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapRealm.java","lineNumber":85,"sourceCode":"    LdapSettingsManager settingsManager) {\n    Map<String, LdapGroupMapping> groupMappings = settingsManager.getGroupMappings();\n    if (!groupMappings.isEmpty()) {\n      return new DefaultLdapGroupsProvider(contextFactories, userMappings, groupMappings);\n    } else {\n      return null;\n    }\n  }\n\n  private static void testConnections(Map<String, LdapContextFactory> contextFactories, boolean ignoreStartupFailure) {\n    try {\n      for (LdapContextFactory contextFactory : contextFactories.values()) {\n        contextFactory.testConnection();\n      }\n    } catch (RuntimeException e) {\n      if (ignoreStartupFailure) {\n        LOG.error(\"IGNORED - LDAP realm failed to start: \" + e.getMessage());\n      } else {\n        throw new LdapException(\"LDAP realm failed to start: \" + e.getMessage(), e);\n      }\n    }\n  }\n\n  @CheckForNull\n  public LdapAuthenticator getAuthenticator() {\n    return authenticator;\n  }\n\n  @CheckForNull\n  public LdapUsersProvider getUsersProvider() {\n    return usersProvider;\n  }\n\n  @CheckForNull\n  public LdapGroupsProvider getGroupsProvider() {\n    return groupsProvider;\n  }","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapRealm.java#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the underlying connection problem indicated by the cause message (check ldap.url, bindDn, bindPassword per server).","Temporarily set sonar.authenticator.ldap.ignoreStartupFailure=true so SonarQube can start while LDAP issues are resolved (logins will fall back to local).","Check LDAP server availability and firewall rules before restarting SonarQube.","Review the full stack trace in sonar.log for which server key failed."],"exampleFix":"// before: startup hard-fails when LDAP is down\n// (no ignore setting)\n// after: tolerate startup failure\nsonar.authenticator.ldap.ignoreStartupFailure: true","handlingStrategy":"fallback","validationCode":"// verify every configured server is reachable before restart\nfor (String key : serverKeys) {\n  String url = config.get(\"sonar.authenticator.ldap.\" + key + \".url\");\n  assertReachable(url); // socket connect to host:port\n}","typeGuard":null,"tryCatchPattern":"try {\n  startRealm();\n} catch (LdapException e) {\n  LOG.error(\"LDAP realm failed to start: {} — falling back to local auth\", e.getMessage());\n  enableLocalAuthenticationOnly();\n}","preventionTips":["Set sonar.authenticator.ldap.ignoreStartupFailure=true in environments where LDAP outages must not block SonarQube startup.","Check LDAP availability before planned restarts/upgrades.","In multi-server setups, ensure all listed servers are live or remove dead keys."],"tags":["ldap","realm-startup","connection-test","sonarqube"],"backgroundTag":"connection-refused","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}