# Troubleshooting

## Agent Not Responding

**Symptom:** You send a message and nothing comes back, or the response never arrives.

**Check:**
1. Ask Maxy: "Check system status" — the `system-status` tool will report whether all services are running
2. Check the platform logs: ask Maxy "Show me the recent logs"
3. If the admin agent itself won't start: restart the platform (see below)

**Common causes:**
- Claude API connectivity issue — check your Claude OAuth connection is still valid
- Platform process has stopped — restart it
- Network issue if accessing remotely — check your Cloudflare tunnel is running

---

## Memory Not Working

**Symptom:** Maxy doesn't remember things you've told it, or search returns nothing.

**Check:**
1. Ask Maxy: "Check the Neo4j connection"
2. Ask Maxy: "Search memory for [something you know was stored]"

**Common causes:**
- Neo4j service stopped — restart the platform, which restarts Neo4j
- Memory index is stale — ask Maxy: "Reindex memory"

---

## Telegram Bot Not Receiving Messages

**Symptom:** You send a message to the bot and nothing happens.

**Check:**
1. Confirm the bot token is correct: ask Maxy "What Telegram bot token is configured?"
2. Verify the bot is running: send `/start` to the bot in Telegram
3. Check the MCP server logs: ask Maxy "Show Telegram plugin logs"

**Common causes:**
- Bot token changed (if you regenerated it in BotFather) — update it by telling Maxy "Update my Telegram bot token"
- Webhook not connected — restart the platform

---

## Plugin Errors

**Symptom:** A tool fails with an error, or a plugin says it can't connect.

**Check:**
1. Ask Maxy: "Show me recent errors"
2. Ask Maxy: "Restart the [plugin name] plugin"

**Common causes:**
- Missing environment variable (API key, token) — the error message will name it; ask Maxy to help configure it
- MCP server crashed — restarting the platform restarts all MCP servers

---

## Restarting the Platform

From the admin interface, ask Maxy: "Restart the platform."

If Maxy itself isn't responding (the page loads but the agent won't connect), try refreshing the browser. If the page itself won't load, the platform process may have stopped — power-cycle the Raspberry Pi by unplugging and reconnecting power, then wait a minute for services to restart automatically.

---

## Checking Logs

Ask Maxy: "Show me the logs" or "Show errors from the last hour."

For specific plugin logs: "Show Telegram logs" or "Show contacts plugin logs."

Maxy has access to all platform logs and can filter them for you.

---

## Cloudflare Tunnel Down (Remote Access Broken)

**Symptom:** You can reach Maxy on your local network but not via your public domain.

**Check:** Ask Maxy "Check the Cloudflare tunnel status."

**Fix:** Ask Maxy "Restart the Cloudflare tunnel."

If the tunnel won't reconnect, re-run the Cloudflare setup: ask Maxy "Reconnect Cloudflare."

If the initial Cloudflare login fails during setup, Maxy will fall back to asking you for a connection key. You can create one in the Cloudflare dashboard (Maxy will guide you through this in the browser).
