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
- Read the wrapped reply code/text in the exception (e.g. 535 = bad credentials).
- Verify SMTP username and password, and that the account is active and allowed to send.
- For XOAUTH2-style flows, refresh the access token before connecting.
- Confirm TLS is established if the server requires it before accepting credentials.
- 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
- Store SMTP credentials in env/secret manager, verify with a smoke test on deploy
- Refresh OAuth tokens before connecting when using token-based auth
- Confirm the mail account is active and permitted to relay
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
- Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.
Related errors
- No shared mechanism. The server offers: ' . ($offered ===…
- provider_missing_credentials
- The server kept challenging
- A command must not span lines
- A message needs at least one recipient
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)