# Troubleshooting

> Fixes for the common Taskhold problems: no taskhold tools in the agent, 401 and 402 responses, a bar that won't move, stale cards and silent streams.

Source: https://taskhold.com/docs/troubleshooting
Last updated: 2026-10-26

Find the symptom, try the fix, and if it still fails, email hello@greatwork.company with what you saw.

## The agent has no taskhold tools

- Claude Code: run claude mcp list. If taskhold is missing, paste a fresh setup URL from Settings, or run the claude mcp add command from /docs/quickstart.
- Restart the client or start a new session after adding the server; most clients load MCP servers at startup.
- Settings shows "Connected" only after the first call. If it never appears, the client isn't reaching https://taskhold.com/api/mcp.

## 401 Unauthorized

| reason | Cause | Fix |
| --- | --- | --- |
| missing_key | No Authorization header was sent | Add Authorization: Bearer atd_sk_... to the MCP config or request |
| bad_header | The header isn't "Bearer <key>" | Write the word Bearer, a space, then the key |
| not_a_taskhold_key | The key doesn't start with atd_sk_ | Use a key from Taskhold Settings |
| unknown_key | Revoked, mistyped, or from a deleted account | Make a new setup URL or key in Settings |

## 402 Subscription required

The key is fine, but the trial ended or the plan was canceled. Restart the plan at /dashboard/settings/billing and retry; the agent's config doesn't change.

## The bar doesn't move

- The task is still todo: the agent has to call taskhold_start before it shows under Working now.
- The task has steps: its bar comes from the steps. Report progress on the running step, or complete steps.
- The agent never calls taskhold_progress or taskhold_plan: add the block from /docs/quickstart to CLAUDE.md or AGENTS.md, or install the plugin's skill.

## A card says quiet or stale

Quiet means no report for 2 minutes, stale means 15. Long test runs or builds are often quiet and fine. A stale card usually means the session ended: open the task's timeline for the last note, then ask the next session to continue it or move it back to todo.

## The event stream stays silent behind a proxy

Some proxies buffer responses. Taskhold sends X-Accel-Buffering: no and Cache-Control: no-transform; if your own proxy sits in between, turn off response buffering for /api/events/stream, or poll /api/events with a cursor instead.

## Desktop notifications don't appear

Click "Notify me" on the live board and allow notifications when the browser asks. They fire while the board is open in a tab; for alerts when it's closed, see /docs/slack-alerts.

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [Taskhold REST API: tasks, steps, progress, curl examples](https://taskhold.com/docs/rest-api.md)
- [Taskhold MCP tools reference (taskhold_*)](https://taskhold.com/docs/mcp-tools.md)