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

  1. Set the Tls options peerName to the hostname that appears in the server certificate's SAN/CN
  2. Use the SMTP server's hostname instead of its IP in the connection config
  3. 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

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.

Related errors


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)