Troubleshooting

OpenMail keeps its data in ~/Library/Application Support/openmail on macOS. The OPENMAIL_HOME environment variable moves it. Paths below are relative to that folder.

OpenMail keeps crashingCopy Anchor Link

OpenMail counts crashes. A crash is either a window that stopped unexpectedly or an app that did not quit cleanly. A crashed window reloads. On the third crash within five minutes, OpenMail restarts in safe mode. Safe mode skips the windows you had open and shows OpenMail safe mode with three buttons:

• Continue opens OpenMail as usual.
• Reset local cache deletes downloaded messages, labels, contacts and search indexes, then downloads mail again. It keeps accounts, settings, drafts, changes waiting to be sent and the sign-ins saved in the keychain.
• Quit closes OpenMail without changing anything. It is the default.

After an unclean exit, OpenMail also checks the database. If the check fails, the same prompt reads The local database couldn't be verified. Then Reset local cache rebuilds the database from the records it can still read. It keeps the damaged file next to mail.db as mail.db.corrupt-<time>-<id>.

If the prompt says to close other OpenMail processes, quit any openmail command or MCP server that is running, then open the app again.

After a crash, the next start opens OpenMail stopped unexpectedly. It shows the crash entries from the diagnostics log. You can send them to the developer as described in Send diagnostics, or close the window.

Free space or clear downloaded mailCopy Anchor Link

Settings → Local cache shows how much space message text, attachments and indexes use.

• Clear all caches removes downloaded message bodies and attachments for every account. Clear account cache does the same for one account. Headers and drafts stay, so search still finds messages. Opening a message downloads its body again.
• Message text cache limit, Attachment cache limit and Keep OpenMail under cap the space OpenMail uses. Starred messages, drafts and messages in the outbox stay even above the limit.
• Compact now returns free database pages to the disk. Wait for syncing and queued changes to finish first.

Settings has no button that resets the whole database. Only the safe mode prompt above does that.

Send diagnosticsCopy Anchor Link

OpenMail writes a diagnostics log to diagnostics/diagnostics.jsonl. It records fixed fields only: event type, time, provider, HTTP method, endpoint template, HTTP status, failure category, the name of a failed internal request and whether it failed, was a defect or was interrupted, the phase and counts of a sync reset, crash and abnormal-exit entries with an exit code, the SQLite result code of a skipped database statistics refresh, and account and folder hashes keyed with a random secret that never leaves your Mac. It never records message content, addresses, full URLs, tokens or stack traces. The export replaces every hash with a number that is valid for that export only. It starts with a summary line: the OpenMail version and build, whether the app is packaged, the macOS, Electron and Node versions, the CPU architecture, the database version, and whether search statistics exist. For each account (numbered, not named) it lists the provider, sync state, time since the last successful sync, how many changes and outbox messages are waiting, the reason sign-in is needed again and the stored failure category. The log rotates at 256 KB and is never uploaded. See Security model.

To report a problem, choose Help → Send feedback…:

1. Enter the Feedback address (see How do I contact the developer?) and pick a Category.
2. Describe what happened.
3. Turn on Attach the redacted diagnostics shown below if you want to include the log. The dialog shows exactly what will be attached.
4. Click Continue to draft. OpenMail opens an email draft from your own account. Review it and send it. Nothing is sent until you do.

Sending feedback needs a connected account.

To report on GitHub instead, click Copy diagnostics in the same dialog, check the text, then click Open GitHub issues and paste it into a new issue.

Settings → Activity lists the actions that you, the command line and AI took on your mail. It does not contain the diagnostics log.

A CLI command or the MCP server failsCopy Anchor Link

The CLI logs only errors by default. The MCP server logs warnings and errors by default, however it starts: openmail mcp, openmail-mcp or OpenMail --mcp. To see more, run the command again with --log-level warn, or --log-level debug for everything:

openmail --log-level warn sync

With --log-level warn, openmail sync prints one line for each account that failed for an unknown reason, with the error's type, reason, HTTP status and message, such as gmail sync failed (full): ProviderError, status 400: …. --log-level debug prints the same line for every other failure, such as a rate limit or a server error. The lines leave out addresses, URL queries and tokens.

The log goes to stderr. Paste it into the GitHub issue. The MCP server writes its log to stderr too, and your AI app keeps that as the server's log. To log more, add --log-level debug after mcp or --mcp in the server's arguments in the AI app's config.

Mail stopped syncingCopy Anchor Link

The bottom of the sidebar shows the sync state: Syncing…, Synced with a time, or Sync failed with the number of failed accounts. Hover over it to see which accounts failed. Click Sync now, or press ⌃⌘R (⌘R with the Gmail shortcut set).

A notice above the message list explains most failures:

• You're offline. Mail syncs again when the connection comes back.
• Couldn't sync an account. Click Try again.
• A sign-in or keychain notice. See the next two sections.
• 3 changes couldn't be saved. Click Details to see which change the server refused.

To check a single account, open Settings → Accounts, select the account and click Check sync health. The report compares the local message count with the server for each folder and shows how many changes are waiting. Copy redacted report copies it with your own folder names replaced by numbers, so you can add it to feedback.

If the counts stay wrong after Sync now, quit OpenMail and open it again. If that does not help, send feedback with the sync health report.

OpenMail keeps asking me to sign inCopy Anchor Link

When an account needs a new sign-in, OpenMail pauses its sync and shows a notice with Sign in again. The account also shows Needs sign-in in Settings → Accounts. The notice names the reason:

If a Google account asks again every week, check the OAuth client it uses. OpenMail's own Google project left Testing mode on 11 October 2026. A build from source uses your own OAuth client, and a client in Testing mode expires sign-ins after 7 days. See Why do I need to sign in again? for provider limits.

The keychain is lockedCopy Anchor Link

OpenMail keeps sign-ins in the macOS keychain. When it cannot read them, the notice reads The keychain is locked. Unlock your computer and sync resumes on its own. and the account shows Keychain is locked in Settings → Accounts.

Unlock your Mac. If macOS asks whether OpenMail may use the keychain item, click Always Allow. If you clicked Deny, OpenMail shows the same notice and tries again on the next sync. A locked keychain never signs you out. If the keychain item itself is gone, OpenMail asks you to sign in again instead.

Inline images show as brokenCopy Anchor Link

OpenMail shows inline images, such as a logo in a signature, from the message's raw source. When that source is over 8 MB, usually because a large attachment sits next to the images, OpenMail does not download it to show them. The images show as broken. Attachments in the same message still download normally when you open or save them.

To see the images, open the message in webmail. Use Message actions (the three dots on the message), then Open in Gmail or Open in Outlook (⇧⌘G). IMAP accounts have no webmail item. For those, Save message as EML… writes the whole message to a file that Apple Mail or another mail app can open. Show original shows the source text only, not the images.

Google says the app is unverifiedCopy Anchor Link

During Gmail sign-in, Google can show Google hasn't verified this app. In a release build this comes from OpenMail's Google project. A build from source has no built-in client and signs in with your own OAuth client. Click Advanced, then Go to OpenMail (unsafe). The FAQ explains why the warning appears. To avoid it, register your own OAuth client.