{"record":{"id":"1ef6adb652abf321","repo":"RocketChat/Rocket.Chat","slug":"connection-failed","errorCode":"Connection_failed","errorMessage":"Connection_failed","messagePattern":"Connection_failed","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/ldap.ts","lineNumber":45,"sourceCode":"\t\t\t200: ajv.compile<{ message: string; success: true }>(messageResponseSchema),\n\t\t\t401: validateUnauthorizedErrorResponse,\n\t\t\t403: validateForbiddenErrorResponse,\n\t\t},\n\t},\n\tasync function action() {\n\t\tif (!this.userId) {\n\t\t\tthrow new Error('error-invalid-user');\n\t\t}\n\n\t\tif (settings.get<boolean>('LDAP_Enable') !== true) {\n\t\t\tthrow new Error('LDAP_disabled');\n\t\t}\n\n\t\ttry {\n\t\t\tawait LDAP.testConnection();\n\t\t} catch (err) {\n\t\t\tSystemLogger.error({ err });\n\t\t\tthrow new Error('Connection_failed');\n\t\t}\n\n\t\treturn API.v1.success({\n\t\t\tmessage: 'LDAP_Connection_successful' as const,\n\t\t});\n\t},\n);\n\nAPI.v1.post(\n\t'ldap.testSearch',\n\t{\n\t\tauthRequired: true,\n\t\tpermissionsRequired: ['test-admin-options'],\n\t\tbody: isLdapTestSearch,\n\t\tresponse: {\n\t\t\t200: ajv.compile<{ message: string; success: true }>(messageResponseSchema),\n\t\t\t401: validateUnauthorizedErrorResponse,\n\t\t\t403: validateForbiddenErrorResponse,","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/ldap.ts#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the server SystemLogger for the underlying error object — it contains the actual LDAP error code and message.","Verify LDAP Host, Port, and protocol (ldap:// vs ldaps://) match the directory server.","Verify the Bind DN and Bind Password are correct and the account is not locked.","Test network connectivity from the Rocket.Chat host to the LDAP server (telnet/curl on the LDAP port).","If using LDAPS, ensure the CA certificate is trusted (LDAP_CA_Cert setting or OS trust store)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight: verify LDAP server is reachable from the client (network-level check)\n// Note: the actual LDAP connection is server-side, so this is a basic network sanity check\nconst ldapHost = settings.LDAP_Host;\nconst ldapPort = settings.LDAP_Port;\n// Use a TCP connectivity check or ldapsearch from the server host","typeGuard":null,"tryCatchPattern":"try {\n  await callLdapTestConnection();\n} catch (e) {\n  if (e.error === 'Connection_failed') {\n    // The real error is in SystemLogger on the server — surface a actionable message\n    console.error('LDAP connection failed. Check SystemLogger for the underlying error.');\n    console.error('Verify: host, port, bind DN, bind password, TLS/CA cert, firewall rules.');\n    return;\n  }\n  throw e;\n}","preventionTips":["Always check SystemLogger after a Connection_failed error — it contains the real LDAP error code.","Validate LDAP host, port, bind DN, and password in settings before testing the connection.","Test connectivity from the Rocket.Chat host to the LDAP server using ldapsearch or telnet before calling the API."],"tags":["ldap","network","configuration","tls"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}