Troubleshooting Guide

This guide helps you diagnose and resolve common issues with InboxZebra.

Viewing Application Logs

InboxZebra uses macOS unified logging. Logs are essential for troubleshooting issues and understanding what’s happening in the app.

Method 1: Console.app (Easiest)

  1. Open Console.app (in /Applications/Utilities/ or search in Spotlight)
  2. In the search bar, enter: subsystem:com.inboxzebra.app
  3. Press Enter to filter InboxZebra logs
  4. Click the “Start” button to stream live logs

Filter by Category: InboxZebra logs are organized into categories. To view specific types of logs, use:

  • subsystem:com.inboxzebra.app AND category:authentication - OAuth and login events
  • subsystem:com.inboxzebra.app AND category:email - Email fetching and processing
  • subsystem:com.inboxzebra.app AND category:llm - Ollama/LLM operations
  • subsystem:com.inboxzebra.app AND category:ui - User interface events
  • subsystem:com.inboxzebra.app AND category:general - Other app events
  • subsystem:com.inboxzebra.app AND category:unsubscribe - Newsletter unsubscribe operations

Method 2: Terminal

# View recent logs (last hour)
log show --predicate 'subsystem == "com.inboxzebra.app"' --last 1h

# Stream live logs
log stream --predicate 'subsystem == "com.inboxzebra.app"' --level debug

# Filter by category (authentication, email, llm, ui, general, unsubscribe)
log show --predicate 'subsystem == "com.inboxzebra.app" AND category == "email"' --last 30m

# Show errors only
log show --predicate 'subsystem == "com.inboxzebra.app" AND messageType == error' --last 1h

# Export logs to file
log show --predicate 'subsystem == "com.inboxzebra.app"' --last 1h > inboxzebra-logs.txt

Authentication Issues

”Authentication failed” or “Token expired”

Symptoms:

  • Can’t connect email account
  • App says token is expired
  • OAuth flow doesn’t complete

Solutions:

  1. Re-authenticate the account:

    • Go to InboxZebra menu → Settings (or press Cmd+,)
    • Click the Accounts tab
    • Click on the account to expand its details
    • Click the trash icon (🗑️) to remove the account
    • Return to the main window
    • Click “Add Account” and reconnect

  2. Check system time:

    • Ensure your Mac’s date and time are set correctly
    • OAuth tokens are time-sensitive
    • Go to System Settings → General → Date & Time

  3. Clear Keychain entries:

    • Open Keychain Access.app
    • Search for “com.inboxzebra.app”
    • Delete any entries
    • Re-authenticate in InboxZebra

  4. Restart InboxZebra:

    • Sometimes a simple restart resolves authentication issues
    • Quit the app completely (Cmd+Q)
    • Wait a few seconds
    • Restart InboxZebra

Email Fetching Issues

”Failed to fetch emails” or “No emails found”

Symptoms:

  • Email fetching fails
  • No emails appear after processing
  • Timeout errors

Solutions:

  1. Check internet connection:

    • Ensure you’re connected to the internet
    • Test by opening a web browser

  2. Reduce date range:

    • Try fetching a smaller date range (e.g., last 7 days instead of 30)
    • Large date ranges can timeout

  3. Check logs for specific errors:

    • View logs in Console.app (see above)
    • Filter by category:email
    • Look for error messages

”Rate limit exceeded”

Symptoms:

  • Error message about rate limits
  • Fetching stops partway through

Solutions:

  1. Wait and retry:

    • Gmail: Wait 1-5 minutes before retrying
    • Office 365: Wait 1-5 minutes before retrying

  2. Reduce batch size:

    • Fetch smaller date ranges at a time
    • Process emails in multiple sessions

Background Sync Issues

”Sync paused” in the status bar

Symptoms:

  • Status bar shows “Sync paused: Ollama not running”, “Sync paused: no network”, etc.
  • Emails not updating automatically

What this means: InboxZebra checks system conditions before each background sync. The status bar shows the specific reason sync was paused. It will resume automatically when the condition is resolved.

Solutions by reason:

Status MessageCauseFix
”Ollama not running”Ollama is not running or not detectedStart Ollama (see below)
“Ollama not responding”Ollama is running but not responding to requestsRestart Ollama or check its logs
”no network”No internet connection detectedCheck Wi-Fi or Ethernet connection
”battery low”Battery below threshold and not plugged inPlug in your Mac or wait until charged
”high CPU usage”System CPU above thresholdClose CPU-intensive apps or wait
”high memory usage”System memory above thresholdClose memory-intensive apps or wait

Starting Ollama:

# If Ollama is installed but not running, open it:
open -a Ollama

# Or start from terminal:
ollama serve

# Verify it's running:
curl http://localhost:11434/api/tags

InboxZebra will detect Ollama within the next sync cycle (default: 5 minutes) and resume syncing automatically. You can also trigger a manual sync by clicking “Process Emails” in the main window.

Adjusting resource thresholds: If sync pauses too aggressively, you can adjust the thresholds in Settings → Background Sync:

  • CPU threshold (default: 70%)
  • Memory threshold (default: 80%)
  • Battery threshold (default: 20%)

LLM / Ollama Issues

”Failed to connect to Ollama” or “LLM request failed”

Symptoms:

  • Categorization fails
  • Error about Ollama connection
  • Timeout during LLM processing

Solutions:

  1. Check Ollama is running:

    ollama list

    If this command fails, Ollama is not running or installed.

  2. Install/start Ollama:

    # Install (if not installed)
# Download from https://ollama.ai

# Pull a model
ollama pull qwen2.5:7b

# Test connection
curl http://localhost:11434/api/tags

  3. Check Ollama URL in Settings:

    • Go to InboxZebra menu → Settings (or press Cmd+,)
    • Click the LLM tab
    • Ensure “Ollama URL” is set to http://localhost:11434 (default)
    • If using a custom Ollama installation, update accordingly

  4. Verify model is downloaded:

    ollama list

    If your configured model isn’t listed, download it:

    ollama pull qwen2.5:7b

  5. Check system resources:

    • Ollama requires significant RAM (16GB minimum for 7B models)
    • Close other memory-intensive applications
    • Monitor Activity Monitor for memory pressure

”LLM response timeout”

Symptoms:

  • Categorization takes too long and times out
  • System becomes unresponsive during processing

Solutions:

  1. Use a smaller model:

    • Try qwen2.5:3b or gemma2:2b for faster processing
    • Go to InboxZebra menu → Settings (Cmd+,) → LLM tab
    • Change the “Model Name” field

  2. Process fewer emails at once:

    • Go to InboxZebra menu → Settings (Cmd+,) → LLM tab
    • Reduce the “Max Emails to Fetch” value
    • Process in smaller batches

Data and Storage Issues

”Database error” or “Failed to save”

Symptoms:

  • Error when saving categories or settings
  • App crashes when accessing data
  • Data doesn’t persist between sessions

Solutions:

  1. Export data before troubleshooting:

    • Go to InboxZebra menu → Settings (Cmd+,)
    • Click the Data tab
    • Click “Export Data”
    • Save backup to a safe location

  2. Check disk space:

    • Ensure you have sufficient free disk space
    • Go to Apple menu () → About This Mac → Storage

  3. Reset UserDefaults (last resort):

    defaults delete com.inboxzebra.app

    Warning: This will delete all categories, learning examples, and settings.

”Encryption error” or “Keychain access denied”

Symptoms:

  • Error about encryption or keychain
  • Can’t access saved tokens

Solutions:

  1. Grant Keychain access:

    • Open Keychain Access.app
    • If prompted, click “Allow” for InboxZebra
    • Check if entries for “com.inboxzebra.app” exist

  2. Reset Keychain permissions:

    • In Keychain Access.app, search for “com.inboxzebra.app”
    • Right-click each entry → Get Info → Access Control
    • Add InboxZebra.app to allowed applications

Touch ID Not Working or Multiple Password Prompts

Symptoms:

  • Touch ID prompt doesn’t appear, only password prompt
  • Multiple password prompts when starting app
  • Multiple authorization requests when updating to v1.0.3

Solutions:

  1. Check Touch ID is enabled:

    • Go to System Settings → Touch ID & Password
    • Ensure Touch ID is enabled for unlocking apps
    • Make sure at least one fingerprint is enrolled

  2. First launch after updating to v1.0.3:

    • You’ll see 8-10 authorization prompts (one per stored credential)
    • This is a one-time migration to the improved keychain system
    • Choose “Always Allow” for each prompt
    • Use Touch ID if available, or your Mac password
    • After this initial setup, you’ll only see a single Touch ID prompt

  3. Clean up legacy keychain entries (automatic):

    • InboxZebra v1.0.3+ automatically cleans up problematic keychain entries after unlock
    • If you still see multiple prompts after the first launch, check logs:
    • Open Console.app: subsystem:com.inboxzebra.app AND category:authentication
    • Look for messages about token cleanup

  4. Manual cleanup (if needed):

    • Open Keychain Access.app
    • Search for “com.inboxzebra.app”
    • Delete all entries you find
    • Restart InboxZebra
    • You’ll need to re-authenticate all accounts once

  5. Verify app signature:

    codesign --verify --deep --strict --verbose=2 /Applications/InboxZebra.app

    Should show “satisfies its Designated Requirement” with no errors.

Note: Starting with v1.0.3, keychain access persists across app updates. After the initial authorization, future updates won’t require re-authorization.

Shared Mailbox Account Changes After Re-authentication

Symptoms:

  • Re-authenticating a shared mailbox changes the account to your personal email
  • Shared mailbox access is lost after token refresh
  • Repeated re-authentication requests for shared mailboxes

Solutions:

  1. Upgrade to v1.0.3 or later:

    • This issue was fixed in v1.0.3
    • Download from https://inboxzebra.com/download
    • Shared mailbox configuration is now preserved during re-authentication
    • Token management improved to prevent repeated re-auth requests

  2. If using older version, remove and re-add the account:

    • Go to Settings → Accounts
    • Remove the affected account
    • Click “Add Account”
    • Authenticate with your personal account (the one you use to access the shared mailbox)
    • Enter the shared mailbox email when prompted
    • The app will remember the configuration for future re-authentications (in v1.0.3+)

  3. Verify configuration after re-authentication:

    • Check that the account name shows the shared mailbox email (not your personal email)
    • If it changed, you may be running an older version - update to v1.0.3+

UI and Performance Issues

App is slow or unresponsive

Symptoms:

  • UI lags when scrolling
  • Processing takes very long
  • App freezes

Solutions:

  1. Reduce cache size:

    • InboxZebra caches up to 10,000 emails
    • Clear cache by removing and re-adding accounts

  2. Close and restart the app:

    • Quit InboxZebra (Cmd+Q)
    • Wait a few seconds
    • Restart

  3. Check system resources:

    • Open Activity Monitor
    • Look for InboxZebra process
    • If CPU or memory usage is extremely high, check logs for issues

  4. Reduce concurrent operations:

    • Don’t fetch emails while categorizing
    • Process one account at a time for large volumes

”Layout broken” or UI elements misaligned

Symptoms:

  • Text overlaps
  • Buttons don’t appear
  • Windows are sized incorrectly

Solutions:

  1. Resize window:

    • Try minimizing and restoring the window
    • Resize the window manually

  2. Reset window preferences:

    defaults delete com.inboxzebra.app NSWindow

  3. Restart the app:

    • Quit and relaunch InboxZebra

Subscription and Licensing Issues

”License key invalid” or “Subscription not active”

Symptoms:

  • Pro/Business features don’t work
  • Error about invalid license
  • Trial ended but subscription shows as inactive

Solutions:

  1. Check and re-enter license key:

    • Go to InboxZebra menu → Settings (Cmd+,)
    • Click the Subscription tab
    • Check your current subscription status
    • If needed, enter your license key exactly as provided in your purchase email

  2. Check subscription status:

    • Go to InboxZebra menu → Settings (Cmd+,)
    • Click the Subscription tab
    • View current tier and expiry date
    • If expired, renew via Paddle

  3. Contact support:

    • If you believe this is an error, contact support with:
      • Your license key (redacted if sharing publicly)
      • Purchase email confirmation
      • Screenshot of the error

Trial already used

Symptoms:

  • Can’t start 14-day trial
  • “Trial already used” message

Solution:

The free trial is limited to one per device. If you’ve already used the trial on this Mac, you’ll need to purchase a subscription to continue using Pro or Business features. Visit https://inboxzebra.com/pricing to choose a plan.

Backup Issues

”Backup creation failed” or “Insufficient disk space”

Symptoms:

  • Manual or automatic backup fails
  • Error message about disk space
  • Backup incomplete

Solutions:

  1. Check available disk space:

    • Click Apple menu () → About This Mac → Storage
    • Need at least 2× your database size free
    • Example: 500 MB database = need 1 GB free
    • Backups require temporary space during creation

  2. Free up disk space:

    • Empty Trash
    • Delete large files or unused applications
    • Move files to external storage
    • Clear browser caches and downloads

  3. Delete old manual/emergency backups:

    • Open Settings → Backups
    • Review manual and emergency backups
    • Delete old ones you no longer need
    • Automatic backups are already managed by retention policy

  4. Check database size:

    • Database location: ~/Library/Application Support/InboxZebra/
    • Look for InboxZebraModel.sqlite and related files
    • If very large (>5 GB), consider archiving old emails in Gmail/Outlook

”Backup restore failed”

Symptoms:

  • Restore operation fails partway through
  • Error message during restore
  • App doesn’t restart properly after restore

Solutions:

  1. Verify backup integrity:

    • InboxZebra automatically verifies SHA-256 hash before restore
    • If corrupted, you’ll see “Backup file is corrupted” error
    • Try a different backup from the same day/week

  2. Check version compatibility:

    • Backups created with newer versions may not restore on older versions
    • Update InboxZebra to the latest version
    • Download from https://inboxzebra.com/download

  3. Ensure app is not running during restore:

    • Quit all InboxZebra instances
    • Check Activity Monitor for any InboxZebra processes
    • Force quit if necessary, then relaunch

  4. Check restore logs:

    • After restore failure, check logs:
    • Open Console.app
    • Filter: subsystem:com.inboxzebra.app
    • Look for “Restore failed at step” messages
    • This shows exactly where the restore failed

  5. Emergency rollback:

    • If restore fails, InboxZebra automatically rolls back to emergency backup
    • Your current data is preserved
    • Check Settings → Backups for the emergency backup created before restore

”Must restart InboxZebra after restore”

Symptoms:

  • Restore completes but data doesn’t appear
  • App shows old data after restore
  • Categories or emails missing

Solution:

This is expected behavior, not an error:

  1. Quit InboxZebra completely:

    • InboxZebra menu → Quit InboxZebra (or Cmd+Q)
    • Ensure it’s fully quit (not just window closed)

  2. Wait a few seconds:

    • Give macOS time to release database locks

  3. Relaunch InboxZebra:

    • Open from Applications folder or Dock
    • Database will reload with restored data

  4. Re-authenticate accounts:

    • Open Settings → Accounts
    • Each account will show “Re-authenticate” button
    • Click and sign in with OAuth (same as original setup)
    • This reconnects to Gmail/Microsoft servers

Why restart is required: InboxZebra keeps the database open while running. Replacing database files requires closing and reopening the database connection.

”Re-authentication required after restore”

Symptoms:

  • After restore, accounts show “Re-authenticate” status
  • Cannot fetch new emails
  • Accounts appear disconnected

Solution:

This is expected and by design:

Why OAuth tokens aren’t backed up:

  • Security: Prevents token theft if backup file is compromised
  • Compliance: OAuth best practices recommend not exporting tokens
  • Safety: Ensures you have control over which Macs can access your email

Re-authentication steps:

  1. Open Settings → Accounts
  2. Click on the first account
  3. Click “Re-authenticate” or the refresh icon
  4. Sign in with your email provider (Gmail or Microsoft)
  5. Grant permissions when prompted
  6. Repeat for each account (takes ~30 seconds per account)

Your data is preserved:

  • All categorized emails restored
  • Categories and labels intact
  • Learning examples and settings restored
  • Only the OAuth connection needs to be re-established

Backup storage growing too large

Symptoms:

  • Backups folder consuming too much disk space
  • Tens of gigabytes used by backups
  • Low disk space warnings

Solutions:

  1. Check total storage used:

    • Open Settings → Backups
    • Look at “Storage used” near the top
    • Review number of backups in each category

  2. Delete old manual backups:

    • Manual backups are never auto-deleted
    • Click on old manual backups
    • Click trash icon to delete
    • Keep only important manual backups (e.g., before major updates)

  3. Delete emergency backups:

    • Emergency backups created before each restore
    • If restore succeeded, you can delete the emergency backup
    • Check creation date to identify restore-related backups

  4. Export and delete:

    • Export important backups to external storage
    • Navigate to ~/Library/Application Support/InboxZebra/Backups/
    • Copy .izbackup files to USB drive or cloud storage
    • Delete local copies after verifying export

  5. Reduce email database size:

    • Archive old emails in Gmail/Outlook (reduces future backup size)
    • Delete unnecessary emails
    • Smaller database = smaller backups

Retention policy:

  • Automatic backups limited to 20 (5 daily + 3 weekly + 12 monthly)
  • Only manual and emergency backups can accumulate indefinitely
  • Review these periodically

Phishing Detection

Email flagged as phishing but seems legitimate

Symptoms:

  • A trusted sender’s email shows a phishing risk level
  • Newsletter or marketing email flagged as suspicious

Common triggers for false positives:

  • Sender uses a brand name in display name but sends from a different domain (e.g., marketing platforms like Mailchimp or SendGrid relaying on behalf of a brand)
  • URL shorteners in newsletters (bit.ly, t.co)
  • Urgency language in legitimate alerts (bank notifications, shipping updates)
  • Bulk email services that fail SPF/DKIM for the brand domain

Solutions:

  1. Check the sender’s actual domain — if it’s a known ESP (e.g., sendgrid.net, mailchimp.com), the email is likely legitimate
  2. Check email authentication headers — legitimate senders usually pass SPF/DKIM for their own sending domain
  3. If false positives persist for a specific type of sender, you can disable phishing detection in Settings > Security

Suspicious email not flagged

Symptoms:

  • An email looks like phishing but has risk level none or low
  • Known scam patterns not detected

Why this happens: Phase 1 phishing detection uses heuristic pattern matching, not AI analysis. It focuses on technical indicators (authentication failures, domain spoofing) and known brand impersonation patterns. It may miss:

  • Novel or targeted phishing that uses legitimate-looking domains
  • Social engineering without technical red flags
  • Compromised legitimate accounts sending phishing
  • New brand impersonation patterns not yet in the detection rules

What to do:

  • Always exercise caution with unexpected requests for credentials or money
  • Check sender domain and authentication headers manually when suspicious
  • Future updates will add AI-powered phishing analysis for deeper detection

Risk levels explained

LevelMeaningTypical Triggers
noneNo phishing indicators detectedEmail passes all checks
lowMinor indicators, likely benignSingle weak signal (e.g., urgency language alone)
mediumMultiple indicators presentFailed authentication + suspicious content
highStrong phishing signalsDomain spoofing + credential request + failed auth

Getting More Help

If you’ve tried the solutions above and still have issues:

  1. Collect diagnostic information:

    • Export logs (see above)
    • Note exact error messages
    • List steps to reproduce the issue

  2. Contact support:

  3. Check for updates:

Remember: Your privacy is important. When sharing logs or screenshots with support, ensure you redact any sensitive information like email addresses, tokens, or personal content.