SonarSource/sonarqube · error · LdapException

Unable to retrieve groups for user %s in server with key <%s

Error message

Unable to retrieve groups for user %s in server with key <%s>

What it means

sonar-auth-ldap wraps any javax.naming.NamingException raised while enumerating a user's groups against an LDAP server in this LdapException. The library searched the group mapping for the given LDAP server key, and the underlying directory operation (bind, search, or attribute read) failed. The original NamingException is logged at debug level and attached as the cause.

Source

Thrown at server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/DefaultLdapGroupsProvider.java:75

  @Override
  public Collection<String> doGetGroups(Context context) {
    return getGroups(context.serverKey(), context.username());
  }

  private Collection<String> getGroups(String serverKey, String username) {
    checkPrerequisites(username);
    Set<String> groups = new HashSet<>();
    if (groupMappings.containsKey(serverKey)) {
      SearchResult searchResult = searchUserGroups(username, serverKey);
      if (searchResult != null) {
        try {
          NamingEnumeration<SearchResult> result = groupMappings
            .get(serverKey)
            .createSearch(contextFactories.get(serverKey), searchResult).find();
          groups.addAll(mapGroups(serverKey, result));
        } catch (NamingException e) {
          LOG.debug(e.getMessage(), e);
          throw new LdapException(format("Unable to retrieve groups for user %s in server with key <%s>", username, serverKey), e);
        }
      }
    }
    return groups;
  }

  private void checkPrerequisites(String username) {
    if (userMappings.isEmpty() || groupMappings.isEmpty()) {
      throw new LdapException(format("Unable to retrieve details for user %s: No user or group mapping found.", username));
    }
  }

  private SearchResult searchUserGroups(String username, String serverKey) {
    try {
      LOG.debug("Requesting groups for user {}", username);
      return userMappings.get(serverKey).createSearch(contextFactories.get(serverKey), username)
        .returns(groupMappings.get(serverKey).getRequiredUserAttributes())
        .findUnique();

View on GitHub (pinned to 184c821202)

Solutions

  1. Enable debug logging to see the underlying NamingException cause (LOG.debug prints it) and fix the root cause (bad DN, filter, or connection).
  2. Verify sonar.authenticator.ldap.group.baseDn, group.objectClass, group.idAttribute match the actual directory schema.
  3. Check network reachability and bind credentials with an ldapsearch command equivalent to the configured group search.
  4. Confirm the serverKey used exists in sonar.authenticator.ldap.servers and has both user and group mappings configured.

Example fix

// before: group mapping pointing at wrong base
sonar.authenticator.ldap.group.baseDn: cn=banks,dc=example,dc=org
// after: correct group container
sonar.authenticator.ldap.group.baseDn: cn=groups,dc=example,dc=org
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling getGroups, verify LDAP group search works
Config config = ...; // sonar config
if (!config.hasKey("sonar.authenticator.ldap.group.baseDn")) {
  throw new IllegalStateException("group.baseDn not configured; skip group sync");
}

Try / catch

try {
  groups = ldapGroupsProvider.getGroups(username);
} catch (LdapException e) {
  LOG.warn("Group retrieval failed for {} (check cause NamingException): {}", username, e.getMessage());
  groups = Collections.emptyList(); // degrade gracefully
}

Prevention

When it happens

Trigger: Calling getGroups (via doGetGroups) for a username whose group search on server with key <serverKey> throws a NamingException — e.g. group search base DN wrong, group objectClass/filter mismatch, network failure to the LDAP server, or anonymous bind not permitted to read group entries.

Common situations: Typo in sonar.authenticator.ldap.group.* settings; group search requires credentials the bind user lacks; LDAP server briefly unreachable; user not found so the group search enumerates over a null/failed result; multi-server setups where only one server has a valid group mapping.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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