RocketChat/Rocket.Chat · error · Error

Connection_failed

Error message

Connection_failed

What it means

ldap.ts:45 wraps any exception from LDAP.testConnection() in a generic Error('Connection_failed'); the underlying ldapjs error (connect, bind, TLS) is logged via SystemLogger at that moment. Manager.testConnection (apps/meteor/server/lib/ldap/Manager.ts:107) rethrows raw connection errors, so the server log is the only place holding the real cause - the API response never includes it.

Solutions

1. Read the SystemLogger entry for this request - it contains the actual ldapjs error (connect ECONNREFUSED, ETIMEDOUT, bind errors, certificate errors)
2. Verify reachability from the Rocket.Chat host: nc -vz <ldap-host> <port> or ldapsearch -H ldaps://host -D bind -w ...
3. Check the host/port/encryption triplet for consistency: 389 + StartTLS vs 636 + LDAPS
4. Validate bind DN, bind password, and CA certificate settings, then test again

if (!reachable(host, port)) {
  // cheap preflight before hitting the test endpoint
  throw new Error(`LDAP host ${host}:${port} unreachable from this machine`);
}
await api.post('/api/v1/ldap.testConnection');

try {
  await api.post('/api/v1/ldap.testConnection');
} catch (err) {
  if (err.response?.body?.error === 'Connection_failed') {
    // transient only if server logs show ETIMEDOUT/ECONNRESET; config errors (bad bind, TLS) need manual fixes
    if (lastLogMatches(/ECONNRESET|ETIMEDOUT/) && attempt < 3) {
      return retryAfter(backoffMs(attempt));
    }
    throw new Error('LDAP connection test failed - check server logs for the underlying ldapjs error');
  }
  throw err;
}

When it happens

Trigger: Wrong LDAP_Host or LDAP_Port; directory server down or unreachable; encryption mismatch (LDAPS against 389 or StartTLS against 636); invalid bind DN or password; TLS certificate validation failure; DNS or firewall blocks between the Rocket.Chat host and the directory.

Common situations: Containers without network access to the directory VLAN; self-signed certificates without a configured CA; Active Directory on 636 with mismatched encryption settings; typos in the host field after migrating directory infrastructure.

Related errors

• Invalid connection details
• LDAP_search_failed
• App metadata download failed
• App package download failed
• could-not-access-webdav

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

Appendix: source

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

			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.testConnection();
		} catch (err) {
			SystemLogger.error({ err });
			throw new Error('Connection_failed');
		}

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

API.v1.post(
	'ldap.testSearch',
	{
		authRequired: true,
		permissionsRequired: ['test-admin-options'],
		body: isLdapTestSearch,
		response: {
			200: ajv.compile<{ message: string; success: true }>(messageResponseSchema),
			401: validateUnauthorizedErrorResponse,
			403: validateForbiddenErrorResponse,

View on GitHub (pinned to b2c16d5842)