{"record":{"id":"640d6cc646787b6b","repo":"appwrite/appwrite","slug":"starttls-handshake-with-this-host-timed-out","errorCode":null,"errorMessage":"STARTTLS handshake with {$this->host} timed out","messagePattern":"STARTTLS handshake with (.+?) timed out","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"packages/smtp/src/Transport/Native.php","lineNumber":107,"sourceCode":"                    ? new TimeoutException('Timed out writing to the server')\n                    : new ConnectionException('Failed writing to the server');\n            }\n\n            $written += $sent;\n        }\n    }\n\n    public function startTls(float $timeout): void\n    {\n        $stream = $this->stream();\n        $this->timeout($timeout);\n\n        // STREAM_CRYPTO_METHOD_TLS_CLIENT means \"TLS 1.0 or better\" here, not\n        // \"TLS 1.0\", so this does not pin the handshake to an obsolete version.\n        $secured = @stream_socket_enable_crypto($stream, true, STREAM_CRYPTO_METHOD_TLS_CLIENT);\n\n        if ($secured !== true) {\n            throw stream_get_meta_data($stream)['timed_out']\n                ? new TimeoutException(\"STARTTLS handshake with {$this->host} timed out\")\n                : new ConnectionException(\"STARTTLS handshake with {$this->host} failed\");\n        }\n\n        $this->tls = true;\n    }\n\n    public function isTls(): bool\n    {\n        return $this->tls;\n    }\n\n    public function close(): void\n    {\n        if ($this->stream !== null) {\n            @fclose($this->stream);\n            $this->stream = null;\n            $this->tls = false;","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/appwrite/appwrite/blob/7eab5f1970bacb06f8cce069c27b7d14a4178153/packages/smtp/src/Transport/Native.php#L89-L125","documentation":"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.","triggerScenarios":"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.","commonSituations":"Firewalls/ISP boxes interfering with STARTTLS on port 587; OpenSSL peer negotiation stalls with misconfigured server certificates; very slow servers with tight client timeouts.","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."],"exampleFix":"// before\n$transport->connect(5.0);\n$transport->startTls(2.0);\n// after\n$transport->connect(5.0);\ntry {\n    $transport->startTls(15.0);\n} catch (TimeoutException $e) {\n    fallbackToImplicitTls465();\n}","handlingStrategy":"retry","validationCode":"// Verify STARTTLS support and reachability before the handshake\n$transport->connect($connectTimeout);\n$greeting = $transport->read($readTimeout);\nif (!str_contains($greeting, '220')) { /* not an SMTP server */ }\n$ehlo = $transport->write(\"EHLO client\\r\n\");\nif (!str_contains($transport->read($readTimeout), 'STARTTLS')) { /* server won't do STARTTLS */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["network","smtp","tls","starttls","timeout","php"],"backgroundTag":"request-timeout","analyzedSha":"7eab5f1970bacb06f8cce069c27b7d14a4178153","analyzedAt":"2026-09-23T00:38:38.905Z","contentChangedAt":"2026-09-23T00:38:38.905Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}