Debug a Failed or Stuck Session
Diagnose Compozy sessions by checking daemon health, session status, event history, repair output, and stored runtime files.
- Audience
- Operators running durable agent work
- Focus
- Guides guidance shaped for scanability, day-two clarity, and operator context.
This guide gets you from "the session is not behaving" to evidence you can act on. It starts with runtime health, then narrows to one session and its durable event trail.
1. Confirm the daemon is reachable
compozy statusFor machine-readable output:
compozy status -o jsonWhat happened: Compozy checked the background daemon through the local runtime control path. If this fails, debug the daemon before debugging the session.
Useful follow-up pages:
2. Check global runtime health
compozy doctor -o jsonLook for unhealthy subsystems before focusing on the agent process. Memory indexing, event storage, or daemon connectivity problems can make a session look broken even when the provider process is not the root cause.
3. Inspect the session status
compozy session status sess_1234 -o jsonCheck:
- session state
- agent name and workspace
- stop reason
- current prompt state
- created and updated timestamps
What happened: the daemon returned the current session record, not a reconstructed transcript. Use this to learn what Compozy thinks the session is doing right now.
4. Read the durable event stream
compozy session events sess_1234Follow live events when the session is still active:
compozy session events sess_1234 --followWhat happened: Compozy read the append-only session event database. This is the best evidence for prompt submission, permission requests, provider messages, tool calls, errors, and stop behavior. The CLI follow mode reads raw persisted events; browser live-tail clients use transcript SSE frames when they need assembled UI messages.
5. Reconstruct the conversation history
compozy session history sess_1234Use history when you need to understand the user-visible turn sequence. Use events when you need operational detail.
6. Run repair when the transcript is interrupted
compozy session repair sess_1234What happened: Compozy inspected the session transcript and reported whether it can repair interrupted state. Repair is for damaged or interrupted transcript state, not a substitute for daemon health checks.
7. Attach or recap only after the state is understood
compozy session recap sess_1234
compozy session resume sess_1234compozy session resume attaches to an eligible live session. If the session is terminal or not
attachable, inspect the deterministic recap, history, and repair output before starting new work.
Read Resume Attach and Replay before treating attach refusal as a
data-loss problem.
Common symptoms
| Symptom | First check | Then read |
|---|---|---|
compozy session prompt hangs | compozy session events --follow | Event Streaming |
| Session is stopped unexpectedly | compozy session status -o json | Session Lifecycle |
| Web UI is stale | compozy status and compozy doctor | Web UI |
| Attach is refused | compozy session list --resumable and compozy session recap | Resume Attach and Replay |
| Agent cannot see project context | compozy workspace info <name> | Workspace Resolver |
| Memory is missing | compozy memory health -o json | Memory System |
Evidence to collect before filing a bug
Collect output from:
compozy status -o json
compozy doctor -o json
compozy session status sess_1234 -o json
compozy session events sess_1234
compozy session history sess_1234Do not include raw secrets, provider API keys, OAuth tokens, or claim tokens in bug reports. Compozy redacts sensitive runtime fields, but copied terminal context may still include local environment details.
Next steps
- Use Choose the Right control surface when you need the best surface for scripts, agents, or browser integrations.
- Use Database Operations when event or catalog storage is the likely problem.
- Use Troubleshooting for daemon, socket, agent, and database failure paths.