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.

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

• Could not find or create a user for LDAP login.
• Could not start TLS connection
• Could not start TLS connection. Further details in the…
• errors.ldap_cannot_connect
• $exception->getMessage()

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

Appendix: 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)