appwrite/appwrite · error · AuthenticationException

Authentication failed

Error message

Authentication failed: {$exception->reply}

What it means

When the SASL exchange fails with a TransactionException (the server returned an error reply to an AUTH command), Client::attempt() wraps it as AuthenticationException("Authentication failed: {reply}") preserving the reply code, so credential/authorization rejections surface as a typed auth failure with the server's message.

Solutions

  1. Read the wrapped reply code/text in the exception (e.g. 535 = bad credentials).
  2. Verify SMTP username and password, and that the account is active and allowed to send.
  3. For XOAUTH2-style flows, refresh the access token before connecting.
  4. Confirm TLS is established if the server requires it before accepting credentials.
  5. Test the credentials against the server with an independent tool.

Example fix

// before
$client->start($user, $password);
// after
try {
    $client->start($user, $password);
} catch (AuthenticationException $e) {
    logger()->error('SMTP auth failed', ['reply' => $e->reply->code]);
}
Defensive patterns

Strategy: try-catch

Validate before calling

if ($user === '' || $secret === '') {
    throw new RuntimeException('SMTP credentials missing');
}

Try / catch

try {
    $client->start($user, $secret);
} catch (AuthenticationException $e) {
    // $e->reply->code: 535 = invalid credentials, 534 = weak mechanism
    log_error('SMTP auth failed', ['code' => $e->reply->code]);
}

Prevention

When it happens

Trigger: Server responds 535 (authentication credentials invalid), 534 (mechanism too weak), 530 (required authentication), or any non-235 final reply during the AUTH conversation initiated by start() with credentials.

Common situations: Wrong username/password in env config; account locked or disabled on the mail server; OAuth token expired for XOAUTH2; password with special characters mis-encoded in config; IP not permitted to authenticate.

Understand the failure class

Related errors


AI-assisted analysis of appwrite/appwrite@7eab5f1970 (2026-09-23). Data as JSON: /api/errors/d0f93feffcba861f. Report an issue: GitHub.

Appendix: source

Thrown at packages/smtp/src/Client.php:345

            $command .= ' ' . ($initial === '' ? '=' : base64_encode($initial));
        }

        try {
            $reply = $this->command($command, [235, 334]);

            for ($challenges = 0; $reply->code === 334; ++$challenges) {
                if ($challenges >= self::MAX_CHALLENGES) {
                    throw new AuthenticationException('The server kept challenging');
                }

                $challenge = base64_decode($reply->text(), true);
                $reply = $this->command(
                    base64_encode($authenticator->respond($challenge === false ? '' : $challenge, $challenges)),
                    [235, 334],
                );
            }
        } catch (TransactionException $exception) {
            throw new AuthenticationException(
                "Authentication failed: {$exception->reply}",
                $exception->reply->code,
                $exception,
            );
        }
    }

    /**
     * MAIL FROM parameters, decided by what the server advertised.
     *
     * @param  string|iterable<string>  $content
     */
    private function parameters(Envelope $envelope, string|iterable $content): string
    {
        $parameters = '';

        if (\is_string($content)) {
            $size = \strlen($content);

View on GitHub (pinned to 7eab5f1970)