Troubleshooting

Common issues and how to fix them. Each problem includes its cause and a step-by-step solution.

AI Classification Issues

Emails aren't being classified

Cause: Your AI key is missing, expired, or out of credits.

1. Open Settings → AI Provider.
2. Verify a key is entered and the status shows as connected.
3. Log in to your AI provider's dashboard and check your billing or credit balance.
4. If the key is invalid, copy a fresh one from your provider. See the API Key Setup Guide.

Classification is slow

Cause: A large backlog of existing emails is being processed, or your AI provider is responding slowly.

1. On first setup, Maexry classifies your existing emails in the background. New incoming emails are prioritized — they'll be classified first.
2. If you're using Ollama, confirm the model is loaded and your machine has enough RAM (8 GB+ recommended).
3. Wait for the initial backlog to clear. Classification speed returns to normal once existing emails are processed.

Emails are miscategorized

Cause: AI classification is probabilistic. Edge cases and ambiguous emails happen.

1. Manually recategorize the email in Maexry.
2. For better accuracy, use a capable model like Gemini 2.0 Flash or GPT-4o mini.

Email Sync Issues

Emails not appearing / sync stopped

Cause: Your OAuth token has expired, or Gmail permissions were revoked.

1. Open Settings → Accounts.
2. Re-authenticate with Google by tapping your account and following the sign-in flow.
3. In your Google Account security settings (myaccount.google.com/permissions), confirm Maexry still has access.

Missing older emails

Cause: Maexry syncs from the point of connection forward by default.

1. Check Settings for a historical sync depth option.
2. If syncing a large mailbox, allow time for the process to complete.

API Key Issues

"Invalid API key" error

Cause: The key was copied incorrectly, has been revoked, or belongs to a different project.

1. Go to your provider's dashboard and copy the key again.
2. When pasting, check for trailing spaces or invisible characters.
3. If the key still fails, generate a new key. Old keys may have been rotated or deleted.

"Quota exceeded" / "Rate limited"

Cause: Your provider billing is exhausted or you've hit a per-minute rate limit.

1. Log in to your provider's billing page and check your credit balance.
2. Add credits or upgrade your API plan if needed.
3. Maexry processes emails in batches. High email volume — especially during initial sync — uses more credits than steady-state operation.

Ollama / Bridge Issues

"Cannot connect to Ollama"

Cause: The Ollama service isn't running, or the URL in Maexry is wrong.

1. Open a terminal and run ollama serve to start the Ollama service.
2. Open Settings → AI Provider → Ollama.
3. Confirm the URL is set to http://localhost:11434 (the default).
4. If Ollama is running on a different port or machine, update the URL accordingly.

Ollama classification is very slow

Cause: The model is too large for your hardware, or the model isn't preloaded.

1. Run ollama run [model-name] in your terminal to preload the model into memory.
2. If performance is still poor, switch to a smaller model.
3. Ensure your machine has at least 8 GB of RAM available. Close other memory-heavy applications if needed.

App Crashes & Performance

App crashes on launch

Cause: A corrupted local database or an incompatible OS version.

1. Force quit Maexry and reopen it.
2. If the crash repeats, try reinstalling the app. Important: Reinstalling removes your local database. Because of Maexry's zero-knowledge architecture, we have no server-side backup of your data. This is a tradeoff — your privacy means your data is yours alone.
3. Verify your device meets the minimum OS requirements.

App is slow or laggy

Cause: A large mailbox with many unprocessed emails, or your device is low on storage.

1. Let background processing complete. Maexry prioritizes new emails, but a large backlog takes time.
2. Free up device storage — the local database needs room to operate.
3. Restart the app.

Billing Issues

Subscription not recognized

Cause: A short delay between Stripe payment processing and subscription activation in the app.

1. Wait a few minutes and restart Maexry.
2. If the issue persists after 15 minutes, contact hello@maexry.ai with your payment receipt. Include the email address you used to purchase.

Charged after cancellation

Cause: Your cancellation was processed after the billing cycle cutoff.

1. Check your email for a cancellation confirmation from Stripe.
2. If you were charged after the confirmed cancellation date, contact hello@maexry.ai for a refund review.

MCP Server Issues

MCP server not starting

Cause: The vault is locked, or MCP is not enabled in Settings.

1. Unlock your vault — the MCP server starts automatically after unlock.
2. Open Settings → Integrations → MCP Server and confirm the toggle is on.
3. If the toggle is on but the server still isn't reachable, quit Maexry completely and relaunch.

"Unauthorized" or "Bearer token invalid" error

Cause: The token has expired (vault was locked since it was generated) or was rotated.

1. Open Settings → Integrations → MCP Server.
2. Tap Rotate Token to generate a fresh token.
3. Update the token in your AI assistant's config (Claude Code, Claude Desktop, etc.) and reconnect.

AI assistant can't find MCP tools / returns empty results

Cause: The server is running but the assistant isn't connected, or it's targeting the wrong account.

1. Verify the server URL and port in your AI assistant's config match what Maexry shows in Settings → Integrations → MCP Server.
2. Confirm at least one account is selected in the Account Access picker.
3. For multi-account setups, pass the correct account_id parameter to the tool. Use xiftly_get_categories with no parameters first — if it returns data, the connection is healthy.

Batch tool returns partial failures

Cause: One or more message IDs are invalid, already deleted, or fail Gmail API validation.

Each batch result includes a per-message success flag and an optional error field. Check the failed entries for message_not_found or invalid_parameter errors. Batch operations continue past individual failures — other messages in the same call are processed normally.

---

Still Need Help?

• Browse the FAQ for quick answers to common questions.
• Chat with our AI support assistant on any page (look for the chat icon).
• Email us directly at hello@maexry.ai.