BookStackApp/BookStack · critical · LdapException

errors.ldap_extension_not_installed

Error message

errors.ldap_extension_not_installed

What it means

LdapException thrown by LdapService::getConnection when the PHP LDAP extension is unavailable — function_exists('ldap_connect') is false and the environment is not 'testing'. The library cannot create any LDAP connection without the extension, so it fails fast with an explanatory message.

Source

Thrown at app/Access/LdapService.php:227

    }

    /**
     * Get the connection to the LDAP server.
     * Creates a new connection if one does not exist.
     *
     * @throws LdapException
     *
     * @return resource|\LDAP\Connection
     */
    protected function getConnection()
    {
        if ($this->ldapConnection !== null) {
            return $this->ldapConnection;
        }

        // Check LDAP extension in installed
        if (!function_exists('ldap_connect') && config('app.env') !== 'testing') {
            throw new LdapException(trans('errors.ldap_extension_not_installed'));
        }

        // 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) {

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Install the PHP LDAP extension (e.g. apt-get install php-ldap / docker-php-ext-install ldap)
2. Enable it: add extension=ldap.so (or php_ldap.dll on Windows) to the relevant php.ini and restart PHP-FPM/Apache
3. Confirm via php -m or phpinfo() that 'ldap' is listed for the SAPI the app uses
4. If LDAP isn't needed, avoid triggering LDAP login/sync features

Example fix

# before
php -m | grep ldap   # (no result)
# after
apt-get install -y php-ldap && systemctl restart php8.2-fpm

if (!function_exists('ldap_connect')) {
    throw new RuntimeException('PHP LDAP extension is not installed/enabled.');
}

try {
    $user = $ldapService->getUserWithAttributes($username);
} catch (\BookStack\Exceptions\LdapException $e) {
    abort(503, 'LDAP is not available on this host: ' . $e->getMessage());
}

When it happens

Trigger: Any call reaching getConnection (getUserWithAttributes, validateUserCredentials, getParentsOfGroup) on a PHP runtime where the php-ldap extension is not installed/enabled, outside the testing environment.

Common situations: php-ldap missing on the host or in the Docker image; extension present for CLI but not enabled for web-server SAPI (or vice versa); upgrade to a new PHP version where the ext wasn't reinstalled; using LDAP features on a host built without LDAP support.

Related errors

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

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