What causes "LDAP_search_failed" in RocketChat/Rocket.Chat?

Check server logs for the underlying error - 'User not found' vs connect/bind tells you which failure class it is

RocketChat/Rocket.Chat · error · Error

LDAP_search_failed

Error message

LDAP_search_failed

What it means

POST /api/v1/ldap.testSearch wraps any failure of Manager.testSearch(username) in Error('LDAP_search_failed') (ldap.ts:79). Manager.testSearch (apps/meteor/server/lib/ldap/Manager.ts:117-133) connects, runs searchByUsername, and throws 'User not found' when the result count is not exactly 1 - so zero matches (wrong username, filter, or Base DN) and ambiguous multi-match filters both map here, as do connect/bind failures. The real cause is logged via the LDAP logger; the API only returns the generic message.

Solutions

Check server logs for the underlying error - 'User not found' vs connect/bind tells you which failure class it is
Verify LDAP_BaseDN actually contains the test user's OU
Match LDAP_Filter to the directory schema: sAMAccountName or userPrincipalName on AD, uid on OpenLDAP
Reproduce with ldapsearch -D <bind> -b <base> '(attr=username)' and require exactly one result

Defensive patterns

Strategy: try-catch

Validate before calling

if (typeof username !== 'string' || username.trim() === '') {
  throw new Error('Provide a non-empty username for ldap.testSearch');
}
await api.post('/api/v1/ldap.testSearch', { username });

Try / catch

try {
  await api.post('/api/v1/ldap.testSearch', { username });
} catch (err) {
  if (err.response?.body?.error === 'LDAP_search_failed') {
    // distinguish via server logs: 'User not found' => filter/baseDN problem; bind/connect errors => connectivity
    hint('Check LDAP_Filter/LDAP_BaseDN against the directory; a passing test must return exactly one match');
    return;
  }
  throw err;
}

Prevention

Validate the filter/baseDN combination with ldapsearch before blaming connectivity - a search must match exactly one entry
Use schema-correct filters (sAMAccountName on AD, uid on OpenLDAP)
Keep the LDAP logger enabled while testing; the API response omits the cause

When it happens

Trigger: Test username that does not exist in the directory; LDAP_Filter mismatched to schema (e.g. (uid=%s) against Active Directory where the attribute is sAMAccountName); LDAP_BaseDN that excludes the user; bind user lacking search rights; filter broad enough to match multiple entries.

Common situations: OpenLDAP defaults used against AD; Base DN not updated after OU restructuring; testing with an email address while the filter matches uid; read-only bind accounts with restricted search scope.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/58f38015d5e6742c. Report an issue: GitHub.

Appendix: source

Thrown at apps/meteor/server/api/v1/ldap.ts:79

			200: ajv.compile<{ message: string; success: true }>(messageResponseSchema),
			401: validateUnauthorizedErrorResponse,
			403: validateForbiddenErrorResponse,
		},
	},
	async function action() {
		if (!this.userId) {
			throw new Error('error-invalid-user');
		}

		if (settings.get<boolean>('LDAP_Enable') !== true) {
			throw new Error('LDAP_disabled');
		}

		try {
			await LDAP.testSearch(this.bodyParams.username);
		} catch (err) {
			SystemLogger.error({ err });
			throw new Error('LDAP_search_failed');
		}

		return API.v1.success({
			message: 'LDAP_User_Found' as const,
		});
	},
);

View on GitHub (pinned to b2c16d5842)