Troubleshooting

Troubleshooting

Accounts and authentication

Symptom Likely cause / fix
Google AUTHENTICATIONFAILED Use OAuth or an app password with 2FA enabled, not the account password
Google OAuth stops working after ~7 days Consent screen still in Testing; use an Internal app or complete verification, or fall back to an app password
Google “access blocked” Redirect URI mismatch, missing test user, or restricted-scope verification required
Outlook login fails Missing OAuth permissions, redirect URI mismatch, or admin consent
Connection timeout Wrong host/port/security: 993 TLS, 465 TLS, 587 STARTTLS, 143 STARTTLS
Sent copy not saved Provider lacks \Sent/APPEND; set the folder manually or adjust auto_saves_sent
Duplicate sent mail auto_saves_sent is false but the provider already saves sent mail
Drafts not saved No \Drafts folder or no APPEND permission
Attachment rejected Provider-specific message size limit

Deployment

Symptom Cause / fix
database_id placeholder error Replace the placeholder in the local wrangler.toml, or set the DB binding in the Pages dashboard
D1_ERROR: no such table: accounts Apply the schema and record the baseline: npm run db:init:remote
D1_ERROR: no such table: labels / message_labels / app_settings / filters / contacts / imap_sync / imap_messages / push_subscriptions / push_prefs / forward_log / deletion_log / sessions / login_attempts / oauth_states / imap_body_cache / imap_sync_locks / schema_migrations Run npm run db:migrate:remote: migrations already recorded are skipped
D1_ERROR: no such column: archive_imap_bodies / archive_key / imap_archive_driver / auto_sync / delete_after_archive / forward_to_json / drafts_folder / spam_folder Run npm run db:migrate:remote, or apply the missing migrations in order
401 loop after login APP_PASSWORD mismatch, cookie blocked, site not served over HTTPS, or the sessions table missing (run node scripts/migrate.mjs remote --from=012)
500 on every API call Missing DB binding, missing secrets, or missing security tables
Google OAuth 503 GOOGLE_MAIL_CLIENT_ID / GOOGLE_MAIL_CLIENT_SECRET missing
Microsoft OAuth 503 MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET missing
OAuth redirect error Redirect URI does not exactly match the app configuration
CPU time limit exceeded Upgrade to Workers Paid
Custom domain error 1014/522 DNS record missing or origin not ready

Storage and relay

Symptom Cause / fix
Drive 403 OAuth scopes, testing-mode token expiry, or Drive not connected
R2 option hidden Missing BUCKET binding
Relay 503 Relay provider not configured for the account and no deployment fallback
Sending from a relay fails with storage_failed No working sent-copy destination: connect Google Drive, create the BUCKET binding, or pick an IMAP mailbox for Sent/Drafts. The send is aborted before the relay is called
too_many_recipients when sending The relay caps recipients per message (to + cc + bcc combined); Cloudflare Email Service allows 50
Custom SMTP relay to smtp.gmail.com (465/587) or smtp.mail.yahoo.com:465 fails with Network connection lost. Those hosts drop the connection from Workers before AUTH. Use an app password on a host that accepts the connection, or an HTTP relay

Upgrades

Symptom Cause / fix
App returns a schema error after deploying The code is newer than the database. Run npm run db:migrate:remote, then retry
Release check says unreachable GitHub API and releases feed both unreachable from the Worker. The app keeps working with the cached answer; run Check again
No update notice on a fork Only releases newer than your build are announced

Where to look next