theonedev/onedev · error · ExplicitException

No user search base specified

Error message

No user search base specified

What it means

OneDev's LDAP authenticator loops over the configured user search bases, searching each until it finds results. The loop assigns 'results' but if the getUserSearchBases() list is empty, the loop body never runs and 'results' stays null, so this ExplicitException is thrown: no user search base was configured.

Source

Thrown at server-plugin/server-plugin-authenticator-ldap/src/main/java/io/onedev/server/plugin/authenticator/ldap/LdapAuthenticator.java:253

        DirContext ctx = null;
        DirContext referralCtx = null;
        try {
            logger.debug("Binding to ldap url '" + getLdapUrl() + "'...");
            try {
            	ctx = new InitialDirContext(ldapEnv);
            } catch (AuthenticationException e) {
        		throw new RuntimeException("Cannot bind to ldap server '" + getLdapUrl() + "': " + e.getMessage());
            }

			NamingEnumeration<SearchResult> results = null;
			for (var userSearchBase: getUserSearchBases()) {
				 results = ctx.search(new CompositeName().add(userSearchBase), 
						userSearchFilter, searchControls);
				 if (results.hasMore())
					 break;
			}
			if (results == null)
				throw new ExplicitException("No user search base specified");
			if (!results.hasMore())
				throw new UnknownAccountException("Unknown account");
            
            SearchResult searchResult = results.next();
            String userDN = searchResult.getNameInNamespace();
            if (!searchResult.isRelative()) {
            	StringBuilder builder = new StringBuilder();
                builder.append(StringUtils.substringBefore(searchResult.getName(), "//"));
                builder.append("//");
                builder.append(StringUtils.substringBefore(
                		StringUtils.substringAfter(searchResult.getName(), "//"), "/"));
                
                ldapEnv.put(Context.PROVIDER_URL, builder.toString());
                logger.debug("Binding to referral ldap url '" + builder.toString() + "'...");
                referralCtx = new InitialDirContext(ldapEnv);
            }
            if (userDN.startsWith("ldap")) {
            	userDN = StringUtils.substringAfter(userDN, "//");

View on GitHub (pinned to d44925c47c)

Solutions

1. Edit the LDAP authenticator in OneDev (Admin > Authentication) and set at least one user search base DN, e.g. 'ou=People,dc=example,dc=com'.
2. Verify the base DN matches your directory structure using ldapsearch.
3. If migrating config, re-enter the search bases that were lost.
4. Test the authenticator by signing in with an LDAP user afterwards.

Example fix

// OneDev authenticator config
// before: User Search Bases: (empty)
// after:  User Search Bases: ["ou=People,dc=example,dc=com"]

// Check LDAP authenticator config before use:
if (authenticator.getUserSearchBases() == null || authenticator.getUserSearchBases().isEmpty())
    throw new IllegalStateException("LDAP authenticator requires at least one user search base");

boolean ldapConfigValid(LdapAuthenticator a) {
    return a.getUserSearchBases() != null && !a.getUserSearchBases().isEmpty()
        && a.getLdapUrl() != null && !a.getLdapUrl().isBlank();
}

try {
    auth.authenticate(token);
} catch (ExplicitException e) {
    // misconfiguration, not a login failure: fix authenticator settings in Admin > Authentication
}

When it happens

Trigger: authenticate() is called for an LDAP authenticator whose 'User Search Bases' list contains zero entries — the for-loop over search bases never executes and results remains null.

Common situations: Administrator left the user search base field blank when creating the LDAP/AD authentication connector; configuration imported or cloned without search bases; an upgrade cleared the field.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• No external password authenticator to authenticate user "{0}
• Unable to change password as you are authenticating via exte
• Unknown account
• Incorrect credentials
• Authentication required

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/116eb8eba9c6e2b2. Report an issue: GitHub.