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

Check SystemLogger for the underlying error — it will reveal whether the issue is a connection, filter, or permission problem.

RocketChat/Rocket.Chat · error · Error

LDAP_search_failed

LDAP_search_failed

Error message

LDAP_search_failed

What it means

Thrown when LDAP.testSearch(this.bodyParams.username) from @rocket.chat/core-services throws. The underlying exception is logged to SystemLogger but only the generic 'LDAP_search_failed' message reaches the caller. The search itself failed — the connection may have succeeded but the query (search base, filter, or user lookup) returned an error.

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 f9d3ec372b)

Solutions

Check SystemLogger for the underlying error — it will reveal whether the issue is a connection, filter, or permission problem.
Verify the LDAP Search Base DN (LDAP_Search_Base) is correct for the directory structure.
Verify the LDAP Filter (LDAP_Filter) uses the correct attribute name for the directory (uid, sAMAccountName, mail, etc.).
Confirm the bind account has search/read permissions on the target OU.
Test the same search externally with ldapsearch to isolate the issue.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate the username format against the LDAP filter before calling testSearch
// The filter typically looks like (uid={0}) or (sAMAccountName={0})
// Ensure the username doesn't contain characters that break the filter
function isValidLdapUsername(username) {
  return typeof username === 'string' && username.length > 0 && /^[a-zA-Z0-9._@-]+$/.test(username);
}
if (!isValidLdapUsername(username)) {
  throw new Error('Invalid username format for LDAP search');
}

Try / catch

try {
  await callLdapTestSearch(username);
} catch (e) {
  if (e.error === 'LDAP_search_failed') {
    console.error('LDAP search failed — check SystemLogger for details.');
    console.error('Verify: Search Base DN, filter attribute, bind permissions, user existence.');
    return;
  }
  throw e;
}

Prevention

Check SystemLogger for the underlying LDAP error after a search failure.
Verify LDAP Search Base DN and filter are correctly configured before testing searches.
Test the equivalent search externally with ldapsearch to isolate configuration issues.

When it happens

Trigger: Incorrect LDAP search base DN or filter configuration, the directory server dropped the connection mid-search, the bind account lacks search permissions, or the username does not match the configured filter syntax.

Common situations: Search Base DN points to the wrong OU; the username attribute in the filter doesn't match the directory schema (e.g., uid vs sAMAccountName); bind account has insufficient ACLs to search the tree; LDAP_Enable is true but other LDAP settings are still defaults.

Related errors

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