Error Reference

When you encounter an error, note the error code and request ID shown in the error message. These help us diagnose issues quickly.

How to Read Errors

API errors return:

{
  "error": "Human-readable message",
  "code": "ERR_TASK_NOT_FOUND",
  "request_id": "abc123def456"
}

The request_id is also in the response header X-Request-Id.

CLI errors are logged to ~/.toban/logs/error.log in JSON format:

{"timestamp":"2026-03-18T10:00:00Z","code":"CLI_AGENT_SPAWN_FAILED","message":"...","context":{}}

API Error Codes

Authentication (ERR_AUTH_*)

Code	HTTP	Cause	User Action
ERR_AUTH_MISSING	401	No API key or session cookie	Log in again or check API key
ERR_AUTH_INVALID	401	API key not found in database	Regenerate API key in Settings
ERR_AUTH_EXPIRED	401	Session older than 7 days	Log in again
ERR_AUTH_FORBIDDEN	403	Agent trying to access other agent's resources	Check task ownership

Tasks (ERR_TASK_*)

Code	HTTP	Cause	User Action
ERR_TASK_NOT_FOUND	404	Task ID does not exist	Check the task ID, it may have been deleted
ERR_TASK_VALIDATION	400	Invalid field values (bad priority, status, etc.)	Check the request body matches the schema
ERR_TASK_DUPLICATE	201 (warning)	Similar task title exists in same sprint	Consider using update_task instead
ERR_TASK_UPDATE_FAILED	500	Database error during update	Retry; if persistent, check logs

Sprints (ERR_SPRINT_*)

Code	HTTP	Cause	User Action
ERR_SPRINT_NOT_FOUND	404	Sprint number does not exist	Check sprint number
ERR_SPRINT_TRANSITION	400	Invalid phase transition (e.g., skipping review)	Follow the flow: active -> review -> retrospective -> completed. Cannot skip phases.
ERR_SPRINT_VALIDATION	400	Invalid sprint data	Check request body

Agents (ERR_AGENT_*)

Code	HTTP	Cause	User Action
ERR_AGENT_NOT_FOUND	404	Agent name not in database	Check agent name spelling
ERR_AGENT_FORBIDDEN	403	Agent trying to modify another agent's task	Assign the task to the correct agent
ERR_AGENT_SPAWN_BLOCKED	409	Same agent already running	Wait for the current task to finish

Review (ERR_REVIEW_*)

Code	HTTP	Cause	User Action
ERR_REVIEW_VALIDATION	400	Missing required review fields	Include all fields: requirement_match, files_changed, code_quality, test_coverage, risks, verdict
ERR_REVIEW_TASK_NOT_FOUND	404	Task not found for review submission	Check task ID

General

Code	HTTP	Cause	User Action
ERR_VALIDATION	400	Request body failed Zod validation	Check the `details` array for specific field errors
ERR_NOT_FOUND	404	Resource not found	Check the URL and ID
ERR_RATE_LIMITED	429	Too many requests (600/min API, 60/min auth)	Wait a moment and retry
ERR_INTERNAL	500	Unexpected server error	Note the request_id and report it
ERR_MAINTENANCE	503	System is in maintenance mode	Wait for maintenance to complete

CLI Error Codes

Agent Lifecycle (CLI_AGENT_*)

Code	Cause	Action
CLI_AGENT_SPAWN_FAILED	Claude CLI failed to start	Check `claude --version`, ensure Claude Code is installed
CLI_AGENT_TIMEOUT	Agent exceeded time limit	Task may be too large; split into smaller tasks
CLI_AGENT_CRASH	Agent process exited unexpectedly	Check agent stdout in terminal panel for details

Git Operations (CLI_GIT_*)

Code	Cause	Action
CLI_GIT_CLONE_FAILED	Repository clone failed	Check GitHub App permissions and repo URL
CLI_GIT_MERGE_FAILED	Merge conflict or worktree issue	Check if files were modified concurrently
CLI_GIT_PUSH_FAILED	Push rejected after rebase retry	Remote may have diverged; pull and retry manually
CLI_GIT_WORKTREE_FAILED	Worktree creation failed	Check disk space and git status

API Communication (CLI_API_*)

Code	Cause	Action
CLI_API_REQUEST_FAILED	API request returned error	Check API URL and network connectivity
CLI_API_AUTH_FAILED	API key rejected	Regenerate API key in dashboard Settings
CLI_API_TIMEOUT	API did not respond in time	Check if Cloudflare Workers is running

Review (CLI_REVIEW_*)

Code	Cause	Action
CLI_REVIEW_LLM_FAILED	Claude CLI review process failed	Check `claude` is accessible and API quota
CLI_REVIEW_LLM_TIMEOUT	Review took longer than 120s	Diff may be too large; this is non-fatal (fallback to text review)
CLI_REVIEW_PARSE_FAILED	LLM output was not valid JSON	Non-fatal; falls back to text review
CLI_REVIEW_API_FAILED	Review report API returned error	Check API logs with request_id

Template Actions (CLI_ACTION_*)

Code	Cause	Action
CLI_ACTION_FAILED	Pre/post action threw an error	Check ~/.toban/logs/error.log for details
CLI_MEMORY_INJECT_FAILED	Failed to inject memories into CLAUDE.md	Non-fatal; agent runs without memories
CLI_MEMORY_COLLECT_FAILED	Failed to collect memories after task	Non-fatal; memories not saved

Troubleshooting

"Auto-review failed. Please review manually."

This means the review_changes post-action failed. Common causes:

Worktree was deleted before review could run
Claude CLI timed out (120s limit for large diffs)
LLM returned non-JSON response

Check ~/.toban/logs/error.log for the specific CLI_REVIEW_* code.

Sprint phase won't change

Valid transitions: active -> review -> retrospective -> completed.

You cannot skip phases (e.g., active -> completed returns ERR_SPRINT_TRANSITION).

Agent not picking up tasks

Check CLI is running (curl localhost:4000/health)
Task must have owner set to an agent role (builder, cloud-engineer, etc.)
Task must be in the current active sprint
Same agent cannot run two tasks simultaneously

Error log location

CLI errors: ~/.toban/logs/error.log

API errors: Cloudflare Workers dashboard > Logs