Skip to main content

Troubleshooting

Solutions for common issues with Aerion.

Connection Issues​

"Connection failed" errors​

If you can't connect to your email server:

  1. Check your internet connection - Ensure you can reach other websites
  2. Verify server settings - Double-check the server hostname and port
  3. Check firewall/antivirus - Ensure ports 993 (IMAP) and 465/587 (SMTP) aren't blocked
  4. Try a different network - Some networks block email ports

OAuth token expired​

For Gmail and Outlook accounts:

  1. Go to Settings > Accounts
  2. Click Edit on the affected account
  3. Click Re-authorize
  4. Complete the OAuth flow in your browser

"Certificate error" or SSL issues​

  • Ensure you're using the correct security setting (SSL/TLS vs STARTTLS)
  • Check that the server hostname matches the certificate
  • For self-hosted servers, ensure the certificate is valid

Sync Problems​

Messages not appearing​

If emails you expect to see aren't showing up:

  1. Check sync period - By default, Aerion syncs the last 180 days
    • Go to Settings > Accounts > Edit to change this
  2. Check the folder - Ensure you're looking in the correct folder
  3. Wait for sync - Large mailboxes can take time to sync initially
  4. Sync Folder - Select the folder, click the sync icon, and choose Sync Folder
  5. Force Re-sync - If that doesn't help, click the sync icon and choose Force Re-sync

Slow initial sync​

First-time sync of large mailboxes can take several minutes. The sync progress is shown in the status bar. Let it complete before expecting all messages.

Sync appears stuck​

If a sync seems to be stuck or unresponsive, click the sync button in the bottom left corner to stop it, then click again to restart the sync.

Sent messages not appearing in Sent folder​

Some servers handle sent mail differently:

  1. Check that the Sent folder is correctly mapped in account settings
  2. Some providers automatically copy sent mail; others require the client to do it

Folders not appearing​

  1. Select the folder, click the sync icon, and choose Force Re-sync
  2. Check if the folder exists in your provider's web interface
  3. Some folders may be hidden by your email provider

Gmail Issues​

"Access denied" or authentication errors​

  • Your OAuth token may have expired - re-authorize the account
  • If using app password, verify it's correct and still active
  • Check if your organization has restrictions on third-party apps

OAuth not working​

Aerion has recently been CASA Tier 2 certified and a LoV was already submitted to Google for review. Until Google gives the final stamp of approval, app passwords may be the only solution.

Try the app password method instead:

  1. Generate an app password in Google Account settings
  2. Remove and re-add your account using app password authentication

"This app isn't verified" warning​

This is expected until Google verifies Aerion. (See above for a more thorough explanation) To proceed:

  1. Click Advanced
  2. Click Go to Aerion (unsafe)
  3. Complete the authorization

Outlook Issues​

Can't connect with regular password​

Outlook/Microsoft 365 requires OAuth authentication. Password-based authentication is not supported.

Use Sign in with Microsoft when adding your account.

"Need admin approval" error​

Your organization's administrator has restricted third-party applications. Contact your IT department to request access, or check if your organization has specific email client requirements.

Linux-Specific Issues​

App won't start​

Ensure WebKit2GTK is installed:

Debian/Ubuntu:

sudo apt install libwebkit2gtk-4.1-0

Fedora:

sudo dnf install webkit2gtk4.1

Arch Linux:

sudo pacman -S webkit2gtk-4.1

If libwebkit2gtk is already installed and Aerion still won't start, try one of the following commands:

Flatpak

flatpak run --env=WEBKIT_DISABLE_DMABUF_RENDERER=1 io.github.hkdb.Aerion
flatpak run --env=WEBKIT_DISABLE_COMPOSITING_MODE=1 io.github.hkdb.Aerion
flatpak run --env=LIBGL_ALWAYS_SOFTWARE=1 io.github.hkdb.Aerion

After figuring out which works, to make the workaround permanent, for example, if DMABUF was the issue:

flatpak override --user --env=WEBKIT_DISABLE_DMABUF_RENDERER=1 io.github.hkdb.Aerion

Binary

WEBKIT_DISABLE_DMABUF_RENDERER=1 aerion
WEBKIT_DISABLE_COMPOSITING_MODE=1 aerion
LIBGL_ALWAYS_SOFTWARE=1 aerion

After figuring out which works, to make the workaround permanent, for example, if DMABUF was the issue:

echo "export WEBKIT_DISABLE_DMABUF_RENDERER=1" >> ~/.profile  # Or whichever file that makes this environment variable stick

Then, logout and log back in.

Notifications not working​

Ensure you have a notification daemon running. On GNOME, notifications work automatically. On other desktops, you may need to install and configure a notification daemon.

Also, if you don't have desktop portal installed on your system or launch Aerion from the terminal, you may want to launch Aerion with the -dbus-notify flag so that it sends notifications directly to dbus.

macOS-Specific Issues​

"App is damaged" or "can't be opened" error​

This happens because Aerion isn't signed with an Apple Developer certificate.

Solution 1: Right-click and Open

  1. Right-click (or Control-click) on Aerion.app
  2. Select "Open"
  3. Click "Open" in the dialog

Solution 2: Remove quarantine attribute

xattr -cr /Applications/Aerion.app

App crashes on startup​

Try removing the configuration and starting fresh:

rm -rf ~/Library/Application\ Support/aerion

Windows-Specific Issues​

Blank window on startup​

This usually indicates a WebView2 issue:

  1. Download the latest WebView2 Runtime from Microsoft
  2. Install it and restart Aerion

Installation blocked by SmartScreen​

Click "More info" and then "Run anyway" to proceed with installation.

Antivirus blocking Aerion​

Some antivirus software may flag Aerion as suspicious (common for new applications). Add an exception for Aerion in your antivirus settings.

Contact Sync Issues​

CardDAV not discovering address books​

  • Verify the URL includes the full path to the DAV endpoint
  • Common formats:
    • Nextcloud: https://server/remote.php/dav
    • Radicale: https://server/user/
    • Baikal: https://server/dav.php
  • Check your username and password
  • Ensure the server supports CardDAV (not just CalDAV)

Google/Microsoft contacts empty​

  • Ensure you granted contacts permission during OAuth authorization
  • Try removing and re-adding the contact source
  • Check that you have contacts in your Google/Microsoft account

Contacts not appearing in autocomplete​

  • Verify the contact source shows a recent sync time
  • Try manually syncing: Settings > Contacts > Sync Now
  • Ensure contacts have email addresses (contacts without email won't appear)

Getting More Help​

If your issue isn't covered here:

  1. Check the GitHub Issues for similar reports
  2. Open a new issue with:
    • Your operating system and version
    • Aerion version
    • Steps to reproduce the problem
    • Any error messages you see
    • Relevant log files (see FAQ for locations)