Skip to main content

​
Error Handling

email-connector maps raw protocol errors to user-friendly messages. This page covers every error you might encounter and how to resolve it.

​
Authentication Errors

Cause: You entered your regular Apple ID password instead of an app-specific password.Fix: Generate an app-specific password at appleid.apple.com → Sign-In and Security → App-Specific Passwords. Use the 16-character password (format: xxxx-xxxx-xxxx-xxxx).
Cause: Two-factor authentication is enabled but you’re using your regular password.Fix: Generate an app password at account.live.com/proofs/manage/additional → App passwords. Use that 16-character password instead.
Cause: Yahoo requires app-specific passwords for third-party access.Fix: Go to login.yahoo.com/myc/security → Generate app password → select “Other App.” Use the generated 16-character password.
Cause: Invalid email address or password.Fix: Verify your email address is correct and that you’re using an app-specific password if your provider requires one. If you have two-factor authentication enabled, you almost certainly need an app password.

​
Connection Errors

Cause: The IMAP server is unreachable. This could be a network issue, incorrect server hostname, or the server is temporarily down.Fix: Check your internet connection. Verify the IMAP server hostname and port in your provider’s setup guide. Wait a minute and try again.
Cause: DNS lookup failed for the IMAP server hostname.Fix: Double-check the server hostname. Common hostnames: imap.mail.me.com (iCloud), outlook.office365.com (Outlook), imap.mail.yahoo.com (Yahoo), imap.fastmail.com (Fastmail).
Cause: The email server’s TLS certificate could not be verified.Fix: This is rare on major providers. If you’re using a self-hosted mail server with a self-signed certificate, you may need to configure certificate trust. For major providers, try again — this is usually a transient issue.
Cause: The email server didn’t respond within the timeout period.Fix: Your provider may be experiencing an outage. Check their status page and try again later. For ProtonMail users, ensure Bridge is running.

​
OAuth Errors

Cause: More than 15 minutes passed between starting the connection flow and submitting credentials.Fix: Start the connection process again from Claude. The authorization flow has a 15-minute window.
Cause: The OAuth redirect URI doesn’t match the allowlist.Fix: This typically means the connector was configured incorrectly. The allowed redirect URIs are:
  • https://claude.ai/api/mcp/auth_callback
  • https://claude.com/api/mcp/auth_callback
  • http://localhost:6274/oauth/callback (Claude Code)
Cause: The code_verifier sent during token exchange doesn’t match the code_challenge from the authorization request.Fix: This is a client-side issue. Try disconnecting and reconnecting the connector in Claude.
Cause: Your access token has expired (tokens last 30 days) or been revoked.Fix: Reconnect the connector in Claude. You’ll go through the setup flow again.

​
MCP Session Errors

Cause: A GET /mcp request was made without an active session.Fix: This is handled automatically by Claude. If you see this in logs, it means a session timed out (30-minute idle timeout) and Claude will create a new one.
Cause: An MCP request was made without an Authorization: Bearer <token> header.Fix: Reconnect the connector in Claude.

​
HTTP Status Codes

CodeMeaning
200Success
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid token
500Server error — check logs or report an issue

​
Reporting Issues

If you encounter an error not listed here, open an issue at github.com/zacslost/email-connector/issues with:
  • Your email provider
  • The error message (screenshot or exact text)
  • Your Node.js version (if self-hosting)