> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging Agents

> Agent not responding? Start here - a quick path from symptom to fix using Activity, Observability, Logs, and Version History.

## Four tools, one flow

When an agent doesn't behave as expected, SlackHive gives you four places to look. Each one answers a different question:

| Tool                | Where                   | Answers                                                                 |
| ------------------- | ----------------------- | ----------------------------------------------------------------------- |
| **Activity**        | Sidebar → Activity      | Is the agent currently running? Did it error?                           |
| **Observability**   | Sidebar → Observability | What happened in the session trace, tokens, tools, latency, and replay? |
| **Logs**            | Agent → Logs tab        | What did the runner log while processing the agent?                     |
| **Version History** | Agent → History tab     | Did a recent change break something?                                    |

Start with Activity for a quick status check. Open Observability for the session trace. Use Logs for raw runner detail, then History if a recent edit caused the issue.

***

## Step 1 — Check Activity

Go to **Activity** in the sidebar. This is the live kanban of every task your agents are running or have recently completed.

* **Active** — the agent is mid-run right now
* **Completed** — finished successfully
* **Errors** — something went wrong

If the job shows **Error**, click into it. The error summary tells you:

* Was it an AI backend error (model timeout, rate limit)?
* Was it an MCP failure (tool server down, credentials expired)?
* Was it a Slack API failure (bot not in channel, token expired)?

Most errors are in one of these three buckets and the fix is quick.

***

## Step 2 — Open the trace

Activity gives you the error. Observability gives you the session trace.

Open **Observability → Sessions**, or click a task from Activity. Each trace can show:

* The incoming message
* Every tool call the agent made
* Model attribution, token usage, and latency
* Sensitive-data markers
* The final response

Look for where the trace stops or goes sideways. Common patterns:

| Symptom                                  | Likely cause                                  |
| ---------------------------------------- | --------------------------------------------- |
| Agent responds but gives wrong answer    | Missing context - check wiki and memory       |
| Agent stops mid-run                      | MCP server error or timeout                   |
| Agent says "I don't have access to that" | Tool not assigned to the agent                |
| No trace at all                          | Agent wasn't running when the message arrived |

Use the agent **Logs** tab when you need the raw runner stream: startup errors, Slack delivery failures, MCP process crashes, or backend exceptions.

***

## Step 3 — Roll Back with Version History

If the agent was working last week and broke after an edit, use **Version History**.

Open the agent → **History tab**. Every save is a snapshot - full diff of what changed: system prompt, skills, memory, tool assignments.

Find the last version that worked, click **Restore**, and you're back to the known-good state in one click. You can then compare the two versions side by side to see exactly what the breaking change was.

<Tip>Before making significant changes to a working agent, note the current version number. If the edit breaks something, you can restore without hunting through history.</Tip>

***

## Common issues and fixes

### Agent not responding in Slack

1. Check that the agent's Slack connection is healthy — agent → **Overview** → **Manage Slack**
2. Confirm the agent process is running — Activity should show recent pings
3. Verify the bot has been invited to the channel (`/invite @agent-name`)

### Scheduled job ran but posted nothing

1. Open Activity → find the job run → check status
2. If Skipped: the skip-notification condition matched, so SlackHive intentionally did not post
3. If Success but silent: check the target channel/DM, Slack delivery errors, and whether your prompt asked for a Slack-visible summary
4. If Error: check the MCP server the agent depends on

### Agent gives outdated answers

1. Check **Memory** - it may be recalling a stale fact. Delete the outdated memory entry.
2. Check the **Wiki** - if the source was re-ingested, the wiki may need a refresh.
3. If the system prompt was recently edited, check Version History for the change.

### MCP tool calls failing

1. Go to Agent → **Tools tab** - verify the MCP server is listed and active
2. Check the MCP server's credentials haven't expired
3. Test the MCP server independently via Test Mode — open the agent → **Test tab** and send a message that triggers the tool

***

## Next steps

<CardGroup cols={2}>
  <Card title="Logs" icon="list" href="/features/logs">
    Full reference for the Logs tab and what each field means.
  </Card>

  <Card title="Activity" icon="wave-pulse" href="/features/activity">
    Live task view with MCP call drill-down.
  </Card>

  <Card title="Version History" icon="clock-rotate-left" href="/features/history">
    Snapshot browsing and one-click restore.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/operations/troubleshooting">
    Startup errors, port conflicts, and CLI issues.
  </Card>
</CardGroup>