{"record":{"id":"cf638ab480c85c83","repo":"BookStackApp/BookStack","slug":"errors-ldap-cannot-connect","errorCode":null,"errorMessage":"errors.ldap_cannot_connect","messagePattern":"errors\\.ldap_cannot_connect","errorType":"exception","errorClass":"LdapException","httpStatus":null,"severity":"critical","filePath":"app/Access/LdapService.php","lineNumber":246,"sourceCode":"        }\n\n        // Disable certificate verification.\n        // This option works globally and must be set before a connection is created.\n        if ($this->config['tls_insecure']) {\n            $this->ldap->setOption(null, LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER);\n        }\n\n        // Configure any user-provided CA cert files for LDAP.\n        // This option works globally and must be set before a connection is created.\n        if ($this->config['tls_ca_cert']) {\n            $this->configureTlsCaCerts($this->config['tls_ca_cert']);\n        }\n\n        $ldapHost = $this->parseServerString($this->config['server']);\n        $ldapConnection = $this->ldap->connect($ldapHost);\n\n        if ($ldapConnection === false) {\n            throw new LdapException(trans('errors.ldap_cannot_connect'));\n        }\n\n        // Set any required options\n        if ($this->config['version']) {\n            $this->ldap->setVersion($ldapConnection, $this->config['version']);\n        }\n\n        // Start and verify TLS if it's enabled\n        if ($this->config['start_tls']) {\n            try {\n                $started = $this->ldap->startTls($ldapConnection);\n            } catch (\\Exception $exception) {\n                $error = $exception->getMessage() . ' :: ' . ldap_error($ldapConnection);\n                ldap_get_option($ldapConnection, LDAP_OPT_DIAGNOSTIC_MESSAGE, $detail);\n                Log::info(\"LDAP STARTTLS failure: {$error} {$detail}\");\n                throw new LdapException('Could not start TLS connection. Further details in the application log.');\n            }\n            if (!$started) {","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/BookStackApp/BookStack/blob/18f8469a1c72f8cc8497e9372635e6dea5028071/app/Access/LdapService.php#L228-L264","documentation":"LdapException thrown by LdapService::getConnection when ldap_connect() returns false, meaning the connection could not even be initiated to the parsed server string. The library wraps this in a clear 'cannot connect' message since nothing further (bind, search) can proceed.","triggerScenarios":"getConnection (via getUserWithAttributes, validateUserCredentials, getParentsOfGroup) calls $this->ldap->connect($ldapHost) and receives false — typically invalid host/port in the 'server' config, unsupported URI scheme, or failure to form a connection resource.","commonSituations":"Malformed server string (wrong ldaps:// scheme, missing/incorrect port, spaces); DNS not resolving the LDAP hostname; firewall/network blocking port 389/636; ldaps used without the extension built against a TLS-capable library.","solutions":["Check the configured LDAP server string format (e.g. ldaps://host:636 or host:389) and correct it","Verify DNS resolution and network reachability: ping/nc the LDAP host and port from the app server","Open firewall/security-group rules for the LDAP port if blocked","Confirm the scheme matches the server (ldaps:// requires TLS-enabled server and extension)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"$host = parse_url($config['server'], PHP_URL_HOST);\nif (!@fsockopen($host, 636, $errno, $errstr, 2)) {\n    throw new RuntimeException(\"Cannot reach LDAP server {$host}: $errstr\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    $user = $ldapService->getUserWithAttributes($username);\n} catch (\\BookStack\\Exceptions\\LdapException $e) {\n    retry(2, fn() => $ldapService->getUserWithAttributes($username), 500);\n    return back()->with('error', trans('errors.ldap_cannot_connect'));\n}","preventionTips":["Validate the server string format (scheme, host, port) in configuration tests","Monitor network/DNS reachability of the LDAP host from app servers","Prefer ldaps:// with correct ports and keep firewall rules documented"],"tags":["ldap","network","connection"],"backgroundTag":"ldap-cannot-connect","analyzedSha":"18f8469a1c72f8cc8497e9372635e6dea5028071","analyzedAt":"2026-09-02T19:49:33.068Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}