Troubleshooting

Errors, what they mean, how to recover.

The full recovery playbook lives next to the skill content:

skill/references/troubleshooting.md

TL;DR — error code cheat sheet

Code	Cause	First move
not_found	Wrong ID or ticket archived	Verify with ticket_search
conflict	Stale etag OR already claimed	ticket_get → retry with fresh ua
seq_blocked	Predecessor not done	ticket_children → finish lower ord first
invalid	Schema violation	Check params against API Guide
internal	Server bug	Retry once; check /health; file an issue

Diagnostic endpoints

# Health + DB connectivity
curl http://localhost:8080/health

# Skill document (tool metadata as TOON)
curl http://localhost:8080/skill

# Server logs (Docker)
docker compose logs -f orkestra

When to file an issue

• Reproducible internal errors
• Errors not in the list above
• Behavior that contradicts the API Guide

→ Open an issue

For security issues, see the Security Policy instead — don’t post them publicly.