RocketChat/Rocket.Chat · error · Error

Connection_failed

Connection_failed

Error message

Connection_failed

What it means

Thrown when LDAP.testConnection() from @rocket.chat/core-services throws an exception. The underlying error is logged to SystemLogger via SystemLogger.error({ err }) but only the generic 'Connection_failed' string reaches the API consumer. This indicates the LDAP directory was unreachable, refused the bind, or returned a protocol error during the connection test.

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

Solutions

  1. Check the server SystemLogger for the underlying error object — it contains the actual LDAP error code and message.
  2. Verify LDAP Host, Port, and protocol (ldap:// vs ldaps://) match the directory server.
  3. Verify the Bind DN and Bind Password are correct and the account is not locked.
  4. Test network connectivity from the Rocket.Chat host to the LDAP server (telnet/curl on the LDAP port).
  5. If using LDAPS, ensure the CA certificate is trusted (LDAP_CA_Cert setting or OS trust store).
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: verify LDAP server is reachable from the client (network-level check)
// Note: the actual LDAP connection is server-side, so this is a basic network sanity check
const ldapHost = settings.LDAP_Host;
const ldapPort = settings.LDAP_Port;
// Use a TCP connectivity check or ldapsearch from the server host

Try / catch

try {
  await callLdapTestConnection();
} catch (e) {
  if (e.error === 'Connection_failed') {
    // The real error is in SystemLogger on the server — surface a actionable message
    console.error('LDAP connection failed. Check SystemLogger for the underlying error.');
    console.error('Verify: host, port, bind DN, bind password, TLS/CA cert, firewall rules.');
    return;
  }
  throw e;
}

Prevention

When it happens

Trigger: Incorrect LDAP host/port in settings, wrong bind DN or credentials, the LDAP server is down, a firewall blocks the connection, or TLS certificate validation fails.

Common situations: LDAP server hostname typo or wrong port (389 vs 636); bind credentials changed on the directory server after initial setup; network/firewall rules blocking outbound traffic to the directory; self-signed or expired CA certificate not trusted by Rocket.Chat; LDAP server requires StartTLS but it is not configured.

Related errors

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