Docs / Reference

Troubleshooting

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

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.