Troubleshooting Decision Tree

Troubleshooting Decision Tree

Start with the symptom and stop when one layer fails. Avoid reinstalling before preserving evidence.

1. Is the dashboard reachable?

• No: check process/pod, /health, edge proxy, token, database volume, and startup logs.
• Yes: continue.

2. Does CLI/API data match the browser?

• No: clear filters, reload once, then inspect WebSocket authentication and proxy upgrades.
• Yes: the displayed data reflects server state; continue.

3. Is the missing or stale session present in SQLite-backed reads?

• No session: investigate hooks, provider discovery, remote sync, or history import.
• Present but stale: compare the newest event/transcript with producer activity.

4. Is the producer still active?

• Yes, transcript advances: ingestion/sync is delayed or failing.
• Yes, transcript does not advance: the provider/tool may be waiting or stuck.
• No: a terminal hook may have been missed; rescan/import and allow reconciliation.
• Unknown: remote/container/Windows liveness may not be observable; rely on transcript/source evidence.

5. Is only one source/provider affected?

• One local provider: inspect that provider's hook config and transcript path.
• One remote provider: inspect provider-specific source status and home path.
• All sources: inspect central service, storage, auth, and capacity.

Symptom index

Symptom	Guide
Active/waiting forever	Stuck Session recipe
Tool failure	Failed Tool Call recipe
Missing older sessions	Recover Missing History
Cost spike	Audit an Expensive Session
Remote source error	Remote Machines
Hook delivery gap	Hook Health
Upgrade regression	Upgrades and Rollback

Escalation bundle

Include version/commit, deployment type, OS, provider, session/source IDs, timestamps with timezone, relevant logs, active filters, expected versus observed result, and a redacted minimal reproduction. Never attach tokens, full databases, or raw sensitive transcripts to a public issue.