appwrite/appwrite · error · TimeoutException

STARTTLS handshake with

Error message

STARTTLS handshake with {$this->host} timed out

What it means

Thrown by Native::startTls() when stream_socket_enable_crypto() does not return true and the stream's timed_out flag is set — the TLS (STARTTLS) handshake did not complete within the socket timeout. A TimeoutException is thrown so callers can tell a slow negotiation apart from a hard handshake failure.

Solutions

  1. Increase the timeout before issuing STARTTLS so slow handshakes can complete.
  2. Catch TimeoutException and retry; if persistent, test with openssl s_client -starttls smtp to isolate the server.
  3. Remove/bypass middleboxes that intercept port 587 traffic.
  4. Fall back to implicit TLS on port 465 if STARTTLS keeps stalling.
  5. Verify the server's TLS stack and certificate chain are healthy.

Example fix

// before
$transport->connect(5.0);
$transport->startTls(2.0);
// after
$transport->connect(5.0);
try {
    $transport->startTls(15.0);
} catch (TimeoutException $e) {
    fallbackToImplicitTls465();
}
Defensive patterns

Strategy: retry

Validate before calling

// Verify STARTTLS support and reachability before the handshake
$transport->connect($connectTimeout);
$greeting = $transport->read($readTimeout);
if (!str_contains($greeting, '220')) { /* not an SMTP server */ }
$ehlo = $transport->write("EHLO client\r
");
if (!str_contains($transport->read($readTimeout), 'STARTTLS')) { /* server won't do STARTTLS */ }

Prevention

When it happens

Trigger: Calling STARTTLS against a server that accepts the command but stalls during the TLS handshake: overloaded TLS terminator, broken middlebox stripping/proxying STARTTLS, or a handshake longer than the timeout.

Common situations: Firewalls/ISP boxes interfering with STARTTLS on port 587; OpenSSL peer negotiation stalls with misconfigured server certificates; very slow servers with tight client timeouts.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors


AI-assisted analysis of appwrite/appwrite@7eab5f1970 (2026-09-23). Data as JSON: /api/errors/640d6cc646787b6b. Report an issue: GitHub.

Appendix: source

Thrown at packages/smtp/src/Transport/Native.php:107

                    ? new TimeoutException('Timed out writing to the server')
                    : new ConnectionException('Failed writing to the server');
            }

            $written += $sent;
        }
    }

    public function startTls(float $timeout): void
    {
        $stream = $this->stream();
        $this->timeout($timeout);

        // STREAM_CRYPTO_METHOD_TLS_CLIENT means "TLS 1.0 or better" here, not
        // "TLS 1.0", so this does not pin the handshake to an obsolete version.
        $secured = @stream_socket_enable_crypto($stream, true, STREAM_CRYPTO_METHOD_TLS_CLIENT);

        if ($secured !== true) {
            throw stream_get_meta_data($stream)['timed_out']
                ? new TimeoutException("STARTTLS handshake with {$this->host} timed out")
                : new ConnectionException("STARTTLS handshake with {$this->host} failed");
        }

        $this->tls = true;
    }

    public function isTls(): bool
    {
        return $this->tls;
    }

    public function close(): void
    {
        if ($this->stream !== null) {
            @fclose($this->stream);
            $this->stream = null;
            $this->tls = false;

View on GitHub (pinned to 7eab5f1970)