Skip to content

Troubleshooting

Jump to bottom
mrdulasolutions edited this page May 13, 2026 · 1 revision

Troubleshooting

If something's broken, look up the symptom here. Almost everything has a one-command fix.

First step always: check the sidecar log.

tail -100 ~/Library/Application\ Support/AOS\ Mail/sidecar.log

Most errors leave a clean stack trace there.

Notifications

Notifications aren't appearing

The single most common cause: macOS TCC desync. The System Settings UI says notifications are allowed, but the underlying permission database silently filters them.

tccutil reset Notifications com.mrdulasolutions.aosmail

Then fully quit AOS Mail (⌘Q, or right-click the dock icon → Quit), relaunch from /Applications, click Test notification in Settings. macOS should re-prompt for permission — grant it.

tccutil reset didn't help

In order, check:

  1. Focus mode active? Click Control Center (top right menu bar), check the Focus tile. Disable any active focus.
  2. Open Notification Center (swipe left from right edge of trackpad or click the date in the menu bar). Are AOS Mail notifications piling up there silently? If yes, banners are filtered but delivery works — your alert style is set to None. Fix in System Settings → Notifications → AOS Mail → Alert style.
  3. Is the alert style "None"? Even with Allow on, style None means no banner. Pick Banners or Alerts.
  4. Watch usernoted while testing. 
    log stream --predicate 'process == "usernoted"' --info
    Click Test in the app. The daemon will log the filter reason in plain text.

If you see entries in Notification Center but no banner ever appears, and Focus is off and alert style is set, that's a macOS bug we've seen on Sonoma 14.4+. Restarting NotificationCenter.app sometimes clears it:

killall NotificationCenter

Sync

Mail isn't syncing

Quick checks:

  1. Account credentials still valid? Settings → Accounts. Red icon = OAuth token expired or IMAP creds rejected.
  2. Re-authenticate. For Gmail: Remove + Add account. For IMAP: Settings → Accounts → click the account → re-enter password.
  3. Log file. tail -50 ~/Library/Application\ Support/AOS\ Mail/sidecar.log | grep -E 'sync|imap|gmail' — look for errors.

"No IMAP credentials for "

The Keychain entry for that account's password was deleted or never saved. Settings → Accounts → click the account → re-enter the password.

Sync is slow

Initial sync (first run on a large mailbox) can take 5–10 minutes. Subsequent syncs use Gmail's History API or IMAP IDLE and are nearly instant. If subsequent syncs feel slow, check the sidecar log for backoff/retry messages — provider rate limiting is the usual cause.

Gmail says "AOS Mail is requesting access to..."

Normal during OAuth. Grant the requested scopes (read/modify/send/labels). If you decline and want to retry: Settings → Accounts → Remove → Add Account → Gmail.

App won't open

"AOS Mail is damaged and can't be opened" / "unidentified developer"

You're either on an old unsigned build or downloaded from somewhere that stripped the codesign metadata.

Fix: download the latest official release from https://github.com/mrdulasolutions/AOS-Mail/releases/latest. Every version since v0.1.0 is signed by Apple Developer ID and notarized.

If you're sure you have the official build and still seeing this:

xattr -d com.apple.quarantine /Applications/AOS\ Mail.app

This removes the quarantine attribute Safari adds to downloaded files. Gatekeeper will re-check the signature on next launch.

App opens, then immediately crashes

tail -50 ~/Library/Application\ Support/AOS\ Mail/sidecar.log

Look for the last error. Common causes:

  • sidecar terminated: signal: Some(9) on macOS 14.4+ — the bundled Node binary lost its signature somehow. Reinstall the .app from the .dmg (the install replaces the binary with a properly-signed copy).
  • SQLite error: database is locked / file is encrypted — data/aos-mail.db got corrupted. Move it aside (mv ~/Library/Application\ Support/AOS\ Mail/data/aos-mail.db ~/aos-mail-backup.db) and re-launch — AOS Mail will create a fresh DB and re-sync.

OpenRouter & Anthropic

"OpenRouter API key not set"

Settings → Agent Tools → AI Models → OpenRouter API Key. Paste your sk-or-... key, click Save. The fix takes effect immediately (since v0.1.9).

HTTP 429: free-models-per-min

OpenRouter caps free models at 16 requests per minute. v0.1.9+ has a client-side limiter that queues calls — but if you see persistent 429s after the limiter is active, it's the upstream provider rate-limiting (e.g., google/gemma-*:free proxies to Google AI Studio, which has its own much tighter per-account quota).

Three options:

  • Switch to a less-throttled free model (DeepSeek, Llama-3.3-70b, Qwen, Mistral).
  • BYOK at OpenRouter — link your own Google AI Studio key at https://openrouter.ai/settings/integrations to use your Google quota instead of OpenRouter's shared pool.
  • Switch to Anthropic (paid) — no rate limits at typical agent volume.

Anthropic 401

Your ANTHROPIC_API_KEY is wrong or revoked. Get a fresh one from https://console.anthropic.com, paste into Settings → Agent Tools → Authentication → Anthropic API Key, click Save.

Updates

Auto-update offers a version but installing fails

Check the sidecar log for the actual error. The most common causes:

  • Network blocked — corporate proxies, etc. The updater fetches from releases/latest/download/latest.json and the asset URL it contains. Both need to be reachable.
  • failed to unpack \._AOS Mail.app`` — you're on a pre-v0.1.8 build trying to update to v0.1.7 specifically. v0.1.7's release tarball contained macOS AppleDouble metadata that broke extraction. Manually install v0.1.8+ from https://github.com/mrdulasolutions/AOS-Mail/releases/latest; auto-update resumes working from there.
  • signature verification failed — your installed app has the v1 updater pubkey embedded, but releases after v0.1.7 are signed with the v2 key. Reinstall manually once; auto-update resumes from v0.1.8 forward.

App says "you're up to date" but I know there's a newer version

Force a check: Settings → General → Updates → Check for Updates. If it still reports up-to-date, the in-app version detection is wrong somehow — quit and relaunch, the check at boot should reconcile.

Performance

App is slow / spinning beach ball

top -pid $(pgrep -f 'aos-mail$') -l 5

If CPU is pinned, the sidecar may be in a triage loop. The agent runs triage on new mail in batches; large initial syncs can hammer Claude calls. Wait it out, or:

  • Settings → Agent Tools → AI Models → switch heavy features (analysis, drafts) to Haiku (faster, cheaper).
  • Pause the agent: Settings → Agent Tools → toggle off until catch-up sync finishes.

Lots of disk space used

~/Library/Application Support/AOS Mail/data/aos-mail.db grows roughly linearly with mail volume. ~10k threads with bodies indexed = ~200-400 MB. Vacuum the database:

sqlite3 ~/Library/Application\ Support/AOS\ Mail/data/aos-mail.db 'VACUUM;'

(Quit AOS Mail first.)

Where to get more help

  1. GitHub Issues — search existing, then open a new one with: macOS version, AOS Mail version, and the relevant 30 lines of sidecar.log. Logs auto-redact OAuth tokens and API keys, but glance over before posting just in case.
  2. Releases — sometimes the version notes mention known-broken behaviors and workarounds.

Reset to a clean slate

Nuclear option, useful when something deeply weird is happening:

# Quit AOS Mail first.
rm -rf ~/Library/Application\ Support/AOS\ Mail
tccutil reset Notifications com.mrdulasolutions.aosmail

# Optionally clear Keychain entries.
security find-generic-password -s com.mrdulasolutions.aosmail
# Repeat `security delete-generic-password -s com.mrdulasolutions.aosmail -a <account>`
# for each entry it lists.

# Drag /Applications/AOS Mail.app to Trash if you want to reinstall fresh.

Then reinstall from the latest .dmg. You'll need to re-add accounts and re-grant permissions.

Home

Users

Developers

Issues · Releases · License

Clone this wiki locally