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

🤖 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 → 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

🎨 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.

🆘 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.