{"record":{"id":"1ef6adb652abf321","repo":"RocketChat/Rocket.Chat","slug":"connection-failed","errorCode":null,"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/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/ldap.ts#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the SystemLogger entry for this request - it contains the actual ldapjs error (connect ECONNREFUSED, ETIMEDOUT, bind errors, certificate errors)","Verify reachability from the Rocket.Chat host: nc -vz <ldap-host> <port> or ldapsearch -H ldaps://host -D bind -w ...","Check the host/port/encryption triplet for consistency: 389 + StartTLS vs 636 + LDAPS","Validate bind DN, bind password, and CA certificate settings, then test again"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if (!reachable(host, port)) {\n  // cheap preflight before hitting the test endpoint\n  throw new Error(`LDAP host ${host}:${port} unreachable from this machine`);\n}\nawait api.post('/api/v1/ldap.testConnection');","typeGuard":null,"tryCatchPattern":"try {\n  await api.post('/api/v1/ldap.testConnection');\n} catch (err) {\n  if (err.response?.body?.error === 'Connection_failed') {\n    // transient only if server logs show ETIMEDOUT/ECONNRESET; config errors (bad bind, TLS) need manual fixes\n    if (lastLogMatches(/ECONNRESET|ETIMEDOUT/) && attempt < 3) {\n      return retryAfter(backoffMs(attempt));\n    }\n    throw new Error('LDAP connection test failed - check server logs for the underlying ldapjs error');\n  }\n  throw err;\n}","preventionTips":["Always read the SystemLogger entry next to a Connection_failed response - the API hides the real cause","Keep host/port/encryption consistent (389+StartTLS vs 636+LDAPS) and verify reachability from the app host, not your laptop","Include LDAP connectivity in staging parity checks before applying directory changes in production"],"tags":["ldap","network","tls","active-directory","connection"],"backgroundTag":"ldap-connection-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}