{"record":{"id":"1cf25bd7ae06147f","repo":"cakephp/cakephp","slug":"cannot-use-an-empty-client-name","errorCode":null,"errorMessage":"Cannot use an empty client name.","messagePattern":"Cannot use an empty client name\\.","errorType":"exception","errorClass":"SocketException","httpStatus":null,"severity":"error","filePath":"src/Mailer/Transport/SmtpTransport.php","lineNumber":317,"sourceCode":"     * Connect to SMTP Server\n     *\n     * @return void\n     * @throws \\Cake\\Network\\Exception\\SocketException\n     */\n    protected function _connect(): void\n    {\n        $this->_generateSocket();\n        if (!$this->_socket->connect()) {\n            throw new SocketException('Unable to connect to SMTP server.');\n        }\n        $this->_smtpSend(null, '220');\n\n        $config = $this->_config;\n\n        $host = 'localhost';\n        if (isset($config['client'])) {\n            if (empty($config['client'])) {\n                throw new SocketException('Cannot use an empty client name.');\n            }\n            $host = $config['client'];\n        } else {\n            $httpHost = env('HTTP_HOST');\n            if (is_string($httpHost) && strlen($httpHost)) {\n                [$host] = explode(':', $httpHost);\n            }\n        }\n\n        try {\n            $this->_smtpSend(\"EHLO {$host}\", '250');\n            if ($config['tls']) {\n                $this->_smtpSend('STARTTLS', '220');\n                $this->_socket->enableCrypto('tls');\n                $this->_smtpSend(\"EHLO {$host}\", '250');\n            }\n        } catch (SocketException $e) {\n            if ($config['tls']) {","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/cakephp/cakephp/blob/1128eba9b09f1946df684811350e26f2cef68fac/src/Mailer/Transport/SmtpTransport.php#L299-L335","documentation":"Thrown by _connect() when the 'client' config key is present but empty. The client name is the hostname sent in the EHLO/HELO greeting and is used by some servers for SPF/reverse-DNS checks. CakePHP refuses an explicitly-set-but-empty value because it would send a malformed greeting.","triggerScenarios":"Configuration like ['client' => ''] — e.g. env('SMTP_CLIENT') resolving to an empty string and being passed straight into the transport config — then triggering _connect() via send() or connect().","commonSituations":"Reading the client hostname from an env var that is set to '' in production; a YAML/dotenv parser converting an unset value to empty string instead of null; copy-pasted config with client => '' left in place.","solutions":["Provide a real fully-qualified hostname, e.g. 'client' => 'mail.example.com'.","If you have no specific client name, remove the 'client' key entirely so CakePHP falls back to env('HTTP_HOST') or 'localhost'.","Sanitize env-derived values: use $client ?: null before injecting into transport config.","Fix the .env/deployment secret so SMTP_CLIENT is unset rather than empty when unused."],"exampleFix":"// before\nnew SmtpTransport(['host' => 'smtp.example.com', 'client' => $envClient]); // $envClient = ''\n// after\nnew SmtpTransport(['host' => 'smtp.example.com', 'client' => ($envClient ?: null)]); // falls back to HTTP_HOST/localhost when null and key absent","handlingStrategy":"validation","validationCode":"$client = $config['client'] ?? null;\nif (array_key_exists('client', $config) && (!is_string($client) || trim($client) === '')) {\n    unset($config['client']); // let CakePHP fall back to HTTP_HOST / localhost\n}","typeGuard":"function hasNonEmptyClient(array $config): bool {\n    return !array_key_exists('client', $config) || (is_string($config['client']) && $config['client'] !== '');\n}","tryCatchPattern":"try {\n    $email->send();\n} catch (\\Cake\\Network\\Exception\\SocketException $e) {\n    if ($e->getMessage() === 'Cannot use an empty client name.') {\n        // rebuild transport without the client key and retry\n    }\n}","preventionTips":["Never pass env() output straight into 'client' — coerce empty strings to null/unset first","Default to omitting 'client' unless your SMTP admin requires a specific HELO name","Validate mailer config in a boot-time check so it fails in CI, not production"],"tags":["smtp","email","configuration"],"backgroundTag":"empty-required-field","analyzedSha":"1128eba9b09f1946df684811350e26f2cef68fac","analyzedAt":"2026-09-12T12:07:00.388Z","contentChangedAt":"2026-09-12T12:07:00.388Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}