Troubleshooting

Troubleshooting

Authentication fails

• Verify the host, username, and authentication method belong to the same account.
• Use an app password when the provider disallows normal-password IMAP access.
• For OAuth, confirm the application permissions, client ID, Google client secret, and Microsoft public-client setting.
• Confirm IMAP access is enabled for the account.

Encrypted token caching is unavailable

Authentication continues with process-local caching. On Linux, install the native GObject/Cairo/libsecret prerequisites and the imap-migration-tools[linux-keyring] extra. Persistent plaintext token storage is intentionally unsupported.

Counts differ

Folder counts can differ because of provider namespace prefixes, Gmail label semantics, duplicate Message-IDs, deleted messages awaiting expunge, or filters that exclude special folders. Compare per-folder output and inspect the relevant logs before enabling deletion.

A migration stops

Rerun with the same migration cache to resume incremental work:

imap-migrate --migrate-cache ./migration-cache

Use --full-migrate only when messages need to be reprocessed despite cached decisions.

The TUI looks incorrect

• Press Alt+0 to reset saved layout settings.
• Use imap-tools --display-mode ascii for limited-Unicode terminals.
• Set NO_COLOR=1 when color output is unsuitable.
• Press F2 for the current keyboard reference.

Reporting a problem

Search or open an issue in the project issue tracker. Remove passwords, OAuth secrets, tokens, email content, and identifying account details from logs before attaching them.