appwrite/appwrite · error · ConnectionException
This transport cannot check a certificate against the…
Error message
This transport cannot check a certificate against the address {$name}. Give Tls a peerName the certificate carries, or ask for Verification::None. What it means
The Swoole transport cannot perform hostname/certificate verification against an IP address (Swoole's TLS layer lacks the peer-name override). If TLS verification is requested and the name to check (peerName or host) is an IP, checkable() throws ConnectionException telling you to supply a peerName or disable verification.
Solutions
- Set the Tls options peerName to the hostname that appears in the server certificate's SAN/CN
- Use the SMTP server's hostname instead of its IP in the connection config
- If the link is internal/trusted and verification is intentionally skipped, set verify: Verification::None
Example fix
// before
new Client('10.0.0.5', 587, tls: new Tls(verify: Verification::Yes)); // host is an IP
// after
new Client('10.0.0.5', 587, tls: new Tls(verify: Verification::Yes, peerName: 'smtp.example.com')); Defensive patterns
Strategy: validation
Validate before calling
if ($tls->verify !== Verification::None
&& filter_var($options->peerName ?? $host, FILTER_VALIDATE_IP) !== false) {
// would throw: set peerName to a cert hostname or disable verification
} Try / catch
try {
$client->connect($host, $port);
} catch (ConnectionException $e) {
// inspect config: IP host without peerName; fix Tls options
} Prevention
- Prefer hostnames over IPs in SMTP config
- Set Tls peerName whenever you connect by IP
- Only use Verification::None on trusted internal links
- Check the peerName matches a SAN/CN on the server certificate
When it happens
Trigger: connect() or startTls() when options->verify is not Verification::None and (options->peerName ?? host) is an IP literal, e.g. smtp host configured as '10.0.0.5' or '127.0.0.1' with verification enabled.
Common situations: Docker/internal networks where the SMTP server is referenced by IP, service discovery returning IPs, or .env pointing _APP_SMTP_HOST at an IP while TLS verification stays on.
Understand the failure class
Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.
- SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Related errors
- STARTTLS handshake with
- The server does not offer STARTTLS
- A command must not span lines
- A path must not span lines
- A read needs a positive length
AI-assisted analysis of appwrite/appwrite@7eab5f1970 (2026-09-23).
Data as JSON: /api/errors/1e11acf9e7753e08.
Report an issue: GitHub.
Appendix: source
Thrown at packages/smtp/src/Transport/Swoole.php:196
return $settings;
}
/**
* Swoole checks the name with X509_check_host(), which reads the DNS entries
* of a certificate and not the address ones. Dialling an IP literal cannot
* pass however the certificate is written — the stream transport checks
* both — so saying so beats a handshake that fails with "SSL verify failed"
* and nothing else.
*/
private function checkable(): void
{
$name = $this->options->peerName ?? $this->host;
if ($this->options->verify === Verification::None || filter_var($name, FILTER_VALIDATE_IP) === false) {
return;
}
throw new ConnectionException(
"This transport cannot check a certificate against the address {$name}. Give Tls a "
. 'peerName the certificate carries, or ask for Verification::None.',
);
}
/**
* The extension declares errCode and errMsg untyped, so neither can be
* dropped into a message without being looked at first.
*/
private function error(Client $client): string
{
$code = $client->errCode;
$message = $client->errMsg;
return \sprintf(
'[%d] %s',
\is_int($code) ? $code : 0,
\is_string($message) && $message !== '' ? $message : 'no reason given',View on GitHub (pinned to 7eab5f1970)