BookStackApp/BookStack · critical · LdapException

errors.ldap_cannot_connect

Error message

errors.ldap_cannot_connect

What it means

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.

Source

Thrown at app/Access/LdapService.php:246

        }

        // Disable certificate verification.
        // This option works globally and must be set before a connection is created.
        if ($this->config['tls_insecure']) {
            $this->ldap->setOption(null, LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER);
        }

        // Configure any user-provided CA cert files for LDAP.
        // This option works globally and must be set before a connection is created.
        if ($this->config['tls_ca_cert']) {
            $this->configureTlsCaCerts($this->config['tls_ca_cert']);
        }

        $ldapHost = $this->parseServerString($this->config['server']);
        $ldapConnection = $this->ldap->connect($ldapHost);

        if ($ldapConnection === false) {
            throw new LdapException(trans('errors.ldap_cannot_connect'));
        }

        // Set any required options
        if ($this->config['version']) {
            $this->ldap->setVersion($ldapConnection, $this->config['version']);
        }

        // Start and verify TLS if it's enabled
        if ($this->config['start_tls']) {
            try {
                $started = $this->ldap->startTls($ldapConnection);
            } catch (\Exception $exception) {
                $error = $exception->getMessage() . ' :: ' . ldap_error($ldapConnection);
                ldap_get_option($ldapConnection, LDAP_OPT_DIAGNOSTIC_MESSAGE, $detail);
                Log::info("LDAP STARTTLS failure: {$error} {$detail}");
                throw new LdapException('Could not start TLS connection. Further details in the application log.');
            }
            if (!$started) {

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Check the configured LDAP server string format (e.g. ldaps://host:636 or host:389) and correct it
2. Verify DNS resolution and network reachability: ping/nc the LDAP host and port from the app server
3. Open firewall/security-group rules for the LDAP port if blocked
4. Confirm the scheme matches the server (ldaps:// requires TLS-enabled server and extension)

$host = parse_url($config['server'], PHP_URL_HOST);
if (!@fsockopen($host, 636, $errno, $errstr, 2)) {
    throw new RuntimeException("Cannot reach LDAP server {$host}: $errstr");
}

try {
    $user = $ldapService->getUserWithAttributes($username);
} catch (\BookStack\Exceptions\LdapException $e) {
    retry(2, fn() => $ldapService->getUserWithAttributes($username), 500);
    return back()->with('error', trans('errors.ldap_cannot_connect'));
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not start TLS connection. Further details in the appli
• $exception->getMessage()
• Could not find or create a user for LDAP login.
• ($isAnonymous ? trans('errors.ldap_fail_anonymous') : trans(
• errors.ldap_extension_not_installed

AI-assisted analysis of BookStackApp/BookStack@18f8469a1c (2026-09-02). Data as JSON: /api/errors/cf638ab480c85c83. Report an issue: GitHub.