Skip to content

Troubleshooting & Error Reference

Troubleshooting & Error Messages Reference

This guide provides an exhaustive troubleshooting directory for every error dialog, warning banner, and diagnostic code in DodaMail. Each entry details the root cause, affected dialog controls, and step-by-step resolution procedures.

1. IMAP & Connection Errors

ERR_IMAP_CONNECTION_FAILED

Dialog Title: Connection to IMAP Server Failed
Message: “Unable to establish connection to <host> on port <port>. Connection timed out after 15000ms.”

  • Root Cause:
    1. The mail server hostname is incorrect or unresolvable by DNS.
    2. The network firewall or ISP blocks outbound connections on port 993 or 143.
    3. The local network is offline.
  • Troubleshooting Steps:
    1. Open Settings -> Accounts -> Edit Account.
    2. Verify the Incoming Server (IMAP Host) spelling (e.g., imap.gmail.com, outlook.office365.com, or mail.domain.com).
    3. Verify the Port: If using SSL/TLS, set to 993. If using STARTTLS, set to 143.
    4. Test basic connectivity in a terminal: 
      nc -zv imap.gmail.com 993
# or
openssl s_client -connect mail.yourdomain.com:993
    5. Click Test Connection in the Account Setup dialog to confirm resolution.

ERR_IMAP_AUTH_FAILED

Dialog Title: Authentication Failed (IMAP)
Message: “The server rejected your login credentials. Verify your username and password.”

  • Root Cause:
    1. Incorrect password or typo in the email address.
    2. The email provider enforces 2-Factor Authentication (2FA) and requires an App-Specific Password (standard for Gmail, Yahoo, Apple iCloud, and Microsoft 365).
    3. IMAP access is disabled in the webmail settings.
  • Troubleshooting Steps:
    1. For Gmail: Ensure IMAP is enabled in Gmail settings. Generate an App Password at https://myaccount.google.com/apppasswords and paste it into DodaMail.
    2. For Outlook / O365: Generate an App Password at https://account.live.com/proofs/AppPassword.
    3. For Custom Domains: Ensure the Username field contains your full email address (user@domain.com), not just the prefix (user).

ERR_IMAP_TLS_CERT_INVALID

Dialog Title: Untrusted SSL/TLS Certificate
Message: “The remote mail server presented a certificate that could not be validated by system root CAs.”

  • Root Cause:
    1. The mail server uses a self-signed SSL certificate.
    2. The server’s Let’s Encrypt certificate has expired.
    3. The hostname in the certificate does not match your entered IMAP Host.
  • Troubleshooting Steps:
    1. Verify the exact domain name listed on the SSL certificate.
    2. If running a private Dovecot/Postfix server, ensure Let’s Encrypt certificates are renewed and system root certificates are updated (sudo apt-get install --reinstall ca-certificates).

2. SMTP & Sending Errors

ERR_SMTP_AUTH_FAILED

Dialog Title: Outgoing Transmission Failed (535 5.7.8)
Message: “Authentication credentials invalid for SMTP relay.”

  • Root Cause:
    1. Your SMTP server requires authentication, but the credentials differ from IMAP.
    2. Password was entered incorrectly.
  • Troubleshooting Steps:
    1. In Settings -> Accounts -> Edit Account, verify that outgoing SMTP authentication is enabled.
    2. Re-enter your password and click Test Connection.

ERR_SMTP_RELAY_DENIED

Dialog Title: Relaying Denied (550 5.7.1)
Message: “Relay access denied for destination address.”

  • Root Cause:
    1. Attempting to send an email using port 25 without authentication.
    2. The “From” email address does not match the authenticated mailbox identity.
  • Troubleshooting Steps:
    1. In the Account Setup dialog, change Outgoing Port from 25 to 587 (STARTTLS) or 465 (SSL/TLS).
    2. Ensure the “From” address in your composer matches your authorized email address.

ERR_ATTACHMENT_TOO_LARGE

Dialog Title: Attachment Size Exceeded
Message: “Total attachments size (32.4 MB) exceeds the maximum transmission limit (25.0 MB).”

  • Root Cause: Standard email protocols restrict single-message payloads to 25 MB.
  • Troubleshooting Steps:
    1. Remove large video or raw image files from the attachments bar.
    2. Compress multiple files into a .dodaz or .zip archive before attaching.
    3. Use cloud sharing links for multi-gigabyte transfers.

3. OS Credential Vault Errors

ERR_KEYRING_LOCKED

Dialog Title: OS Credential Vault Locked
Message: “The operating system keyring denied access. Passphrase required.”

  • Root Cause:
    1. On Linux: GNOME Keyring or KWallet was not unlocked automatically upon user login (common in auto-login or SSH X11 forwarding sessions).
    2. Master login password was recently changed.
  • Troubleshooting Steps:
    1. In the Keyring Authentication Dialog, enter your system user login password and click Unlock Vault.
    2. Check “Remember for this session” to prevent subsequent prompts.

4. SQLite Database & Storage Errors

ERR_SQLITE_BUSY

Dialog Title: Database Locked
Message: “The local database file is currently locked by another operation.”

  • Root Cause: Concurrent background operations (such as high-volume indexing during an initial sync) temporarily locked the database file.
  • Troubleshooting Steps:
    1. DodaMail automatically retries locked operations using exponential backoff.
    2. If lock persists, close any secondary DodaMail CLI instances.
    3. Restart DodaMail: SQLite WAL recovery will automatically clear stale lockfiles.

ERR_SQLITE_CORRUPT

Dialog Title: Database Malformed
Message: “The local SQLite database could not be read or recovered.”

  • Root Cause: Hardware sudden power loss or hard drive failure during an unbuffered write cycle.
  • Troubleshooting Steps:
    1. Do not panic: Your emails are safely preserved on your remote IMAP server.
    2. Open Settings -> Data & Storage -> Restore from Backup and select your latest .dodabak file.
    3. Alternatively, click Purge All Local Data & Reset: DodaMail will recreate a pristine database and re-download your message history from your IMAP server.

5. Licensing & Device Seats Errors

ERR_LICENSE_KEY_INVALID

Dialog Title: Invalid License Key
Message: “The license key entered was not found in the DodaTech store registry.”

  • Root Cause: Typographical error or space in the license key string.
  • Troubleshooting Steps:
    1. Check your purchase confirmation email from https://dodatech.com/shop/.
    2. Format must match: DODA-XXXX-XXXX-XXXX-XXXX.
    3. Click “Copy” directly from your order page and paste it into the field.

ERR_LICENSE_SEAT_LIMIT_REACHED

Dialog Title: Device Seat Limit Reached (2/2 Active)
Message: “This license key is already actively assigned to two other computers.”

  • Root Cause: Standard licenses allow 2 concurrent active seats. Attempting to activate a 3rd machine triggers this protection.
  • Troubleshooting Steps:
    1. The dialog automatically transitions into the Atomic Seat Transfer Screen.
    2. Inspect the table showing your existing registered devices (e.g., Old-Laptop and Office-PC).
    3. Select the obsolete machine and click “Transfer Seat to This Machine”.
    4. The remote server will deactivate the old device and activate your current computer immediately.

ERR_LICENSE_EXPIRED

Dialog Title: Evaluation Period Expired
Message: “Your 30-day free trial has concluded. Please activate a license to continue sending.”

  • Root Cause: 30 days have elapsed since initial application launch.
  • Troubleshooting Steps:
    1. You can still read, search, and export all your local emails.
    2. Click “Buy License Now” and use coupon code FLAT30 for an exclusive 30% discount at https://dodatech.com/shop/.
    3. Enter your purchased key in the Software Registration Dialog to restore full sending capabilities.

6. Backup & Restore Errors

ERR_BACKUP_INTEGRITY_MISMATCH

Dialog Title: Corrupted Backup File
Message: “SHA-256 integrity verification failed for the selected archive.”

  • Root Cause: The .dodabak archive was incompletely downloaded or corrupted during file transfer.
  • Troubleshooting Steps:
    1. Re-copy the backup archive from the original source storage device.
    2. Verify file size matches original export.