Debug a failed or stuck session

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 status

For machine-readable output:

compozy status -o json

What 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:

• Daemon Operations
• Troubleshooting
• File Locations

2. Preserve a support bundle before mutation

When the daemon is reachable, create its bounded, redacted incident artifact before changing configuration, repairing a transcript, or removing a session:

compozy support bundle --yes --output /tmp/compozy-support-bundle.tar.gz

The bundle contains status, doctor diagnostics, provider metadata, redacted config, event summaries, and a bounded log tail. It excludes transcripts and per-session event databases. Keep the archive private; redaction does not replace secure handling.

3. Check global runtime health

compozy doctor -o json

Look 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.

4. Inspect the session status

compozy session status sess_1234 -o json

Check:

• session state
• agent name and workspace
• stop reason
• attachability
• failure kind and bounded summary
• 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.

5. Read the durable event stream

compozy session events sess_1234

Follow live events when the session is still active:

compozy session events sess_1234 --follow

What 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.

6. Reconstruct the conversation history

compozy session history sess_1234

Use history when you need to understand the user-visible turn sequence. Use events when you need operational detail.

7. Dry-run repair when the transcript is interrupted

compozy session repair sess_1234 --dry-run -o json

Repair can append events only when the session is stopped. Without --force, mutation is limited to stop reasons agent_crashed and error. If the dry run reports safe actions for an eligible session, apply them explicitly:

compozy session repair sess_1234 -o json

--force broadens mutation to other stopped-session reasons; it does not make an active session eligible and does not restart a terminal session. Repair is append-only transcript terminalization, not a substitute for daemon health checks.

8. Attach or recap only after the state is understood

compozy session recap sess_1234

If status reports active and attachable: true, attach to that live session:

compozy session resume sess_1234

If the session is terminal or not attachable, use recap, history, events, and repair output as evidence, then create a new session for new work. Read Resume Attach and Replay before treating attach refusal as a data-loss problem.

Common symptoms

Evidence to collect before filing a bug

Create a support bundle first, then retain the exact session commands you used:

compozy support bundle --yes --output /tmp/compozy-support-bundle.tar.gz
compozy session status sess_1234 -o json
compozy session repair sess_1234 --dry-run -o json

Do not include raw secrets, provider API keys, OAuth tokens, or claim tokens in bug reports. Compozy redacts sensitive runtime fields in the bundle, but copied terminal context and session transcripts may still contain private project or prompt content.

Next steps

• Use Choose a 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.