{"record":{"id":"f4b1b11a7cdb2622","repo":"BookStackApp/BookStack","slug":"could-not-start-tls-connection","errorCode":null,"errorMessage":"Could not start TLS connection","messagePattern":"Could not start TLS connection","errorType":"exception","errorClass":"LdapException","httpStatus":null,"severity":"error","filePath":"app/Access/LdapService.php","lineNumber":265,"sourceCode":"        }\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) {\n                throw new LdapException('Could not start TLS connection');\n            }\n        }\n\n        $this->ldapConnection = $ldapConnection;\n\n        return $this->ldapConnection;\n    }\n\n    /**\n     * Configure TLS CA certs globally for ldap use.\n     * This will detect if the given path is a directory or file, and set the relevant\n     * LDAP TLS options appropriately otherwise throw an exception if no file/folder found.\n     *\n     * Note: When using a folder, certificates are expected to be correctly named by hash\n     * which can be done via the c_rehash utility.\n     *\n     * @throws LdapException\n     */","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/BookStackApp/BookStack/blob/18f8469a1c72f8cc8497e9372635e6dea5028071/app/Access/LdapService.php#L247-L283","documentation":"startTls() returned false without throwing, meaning the LDAP layer reported the TLS negotiation failed but did not raise an exception. LdapService treats a falsy startTls() result as fatal and throws this message. Like error 10, the underlying LDAP diagnostic was not attached to this exception.","triggerScenarios":"getConnection() on the ldap:// path where $this->ldap->startTls($ldapConnection) returns false — typically the same failure modes as the thrown-exception variant (cert verification failure, server rejecting the extended operation) but surfaced as a false return instead of an exception depending on the LDAP wrapper implementation.","commonSituations":"Using the LdapConnection wrapper where startTls returns bool; servers that close the connection during handshake; misconfigured CA certs so verification fails silently; connecting to a plain TCP port that is not LDAP at all.","solutions":["Enable LDAP debug logging (LDAP_OPT_DEBUG_LEVEL / ldap_set_option diagnostics) and check application logs for the handshake failure cause","Validate CA certificate configuration for the LDAP TLS connection","Test STARTTLS directly against the server with ldapsearch -ZZ to reproduce outside PHP","Switch to ldaps:// (port 636) if STARTTLS is unreliable in your environment","Confirm the target host/port actually speaks LDAP and supports the StartTLS extended operation"],"exampleFix":"// before\nLDAP_HOST=ldap://ldap.example.com:389 with START_TLS=true\n// after (if STARTTLS keeps failing)\nLDAP_HOST=ldaps://ldap.example.com:636 with START_TLS=false","handlingStrategy":"try-catch","validationCode":"// probe the server first\nexec(\"echo | openssl s_client -connect {$host}:389 -starttls ldap 2>/dev/null | grep 'Verify return code'\", $out, $code);\nif ($code !== 0) { /* STARTTLS handshake will fail */ }","typeGuard":null,"tryCatchPattern":"try {\n    $conn = $ldapService->validateUserCredentials($username, $password);\n} catch (LdapException $e) {\n    if ($e->getMessage() === 'Could not start TLS connection') {\n        Log::error('STARTTLS returned false; check CA config and server TLS support');\n    }\n}","preventionTips":["Use ldaps:// (636) when STARTTLS is unreliable","Validate CA cert configuration before deployment","Monitor LDAP server TLS certificate expiry","Test handshake with openssl s_client -starttls ldap during setup"],"tags":["ldap","tls","starttls"],"backgroundTag":"ldap-starttls-failed","analyzedSha":"18f8469a1c72f8cc8497e9372635e6dea5028071","analyzedAt":"2026-09-02T19:49:33.068Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}