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
- Increase the timeout before issuing STARTTLS so slow handshakes can complete.
- Catch TimeoutException and retry; if persistent, test with openssl s_client -starttls smtp to isolate the server.
- Remove/bypass middleboxes that intercept port 587 traffic.
- Fall back to implicit TLS on port 465 if STARTTLS keeps stalling.
- 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
- Use generous timeouts for TLS negotiation on slow links.
- Test with openssl s_client -starttls smtp when STARTTLS stalls.
- Bypass/fix middleboxes that intercept port 587.
- Fall back to implicit TLS (465) where the server supports it.
- Retry once on TimeoutException before failing the message.
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.
- SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
- Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
Related errors
- STARTTLS handshake with
- Cannot reach
- Timed out waiting for the server
- Timed out writing to the server
- Failed writing to the server
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)