Troubleshooting & Failure Cookbook
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting & Failure Cookbook serves as a comprehensive guide for diagnosing and resolving issues within the cxs local Codex session retrieval system. It focuses on identifying common failure modes—such as index unavailability, coverage gaps, and query mismatches—and provides standardized workflows for recovery.
The scope of this cookbook covers the interaction between the cxs CLI, the SQLite indexing engine, and the raw Codex session logs. It is designed to help developers and agents move from a state of "zero results" or "error exit" to a successful Progressive Workflow.
Sources: skill-packages/cxs/references/failure-cookbook.md:1-5, README.md:1-10
Common Failure Modes & Quick Fixes
Most issues in cxs arise from the state of the local index or the specificity of the query selector. The following table summarizes common symptoms and their prescribed resolutions.
| Symptom | Initial Command | Recommended Action |
|---|---|---|
find returns zero results | status --selector '<json>' --json | Check requestedCoverage. If stale/missing, run sync --selector. |
sync fails with per-file errors | sync --selector '<json>' --json | Inspect errorDetails[]. Use --best-effort only if partial success is acceptable. |
selector_required error | N/A | Provide an explicit --selector. sync has no default range. |
index_unavailable error | status --json | The SQLite index does not exist. Run sync --selector to initialize. |
database is locked (SQLITE_BUSY) | Retry command | Retry once. If persistent, wait for existing sync processes to finish. |
| CJK (Chinese/Japanese/Korean) zero results | N/A | Use at least two characters or combine with English keywords/selectors. |
Sources: skill-packages/cxs/references/failure-cookbook.md:7-20, skill-packages/cxs/references/cli-surface.md:10-15
Index Unavailability & Initialization
The cxs system requires a populated SQLite index to answer content queries (find, list, read-*). If a query is attempted before any synchronization has occurred, the CLI returns an index_unavailable error code.
Diagnostic Flow
When an agent or user encounters a missing index, the following sequence should be followed to establish coverage:
The sync --selector command is the only mechanism to create the index; there is no separate init command.
Sources: skill-packages/cxs/references/failure-cookbook.md:46-60, skill-packages/cxs/references/cli-surface.md:10-14
Coverage Gaps and Staleness
A common failure is a "False Negative" where a session exists in raw logs but is not returned by find. This usually indicates that the index coverage for the specific cwd or date_range is missing or out of date (stale).
Requested Coverage Logic
The status --selector '<json>' --json command provides a requestedCoverage object which dictates the next step:
recommendedAction: "query": The index is fresh. The issue is likely the query keywords or ranking.recommendedAction: "sync": The index is missing or the source files have changed since the last sync.
Advanced Query Troubleshooting
Time-Based Ranking Issues
By default, find sorts by relevance. When a user asks for "the latest" or "recent" sessions, relevance-based ranking may hide newer results behind higher-scoring older sessions.
Fix: Use --sort ended and exclude the current session to avoid self-hits:
cxs find "keyword" --sort ended --exclude-session <current_uuid> --json
Sources: skill-packages/cxs/references/failure-cookbook.md:78-85, skill-packages/cxs/SKILL.md:45-50
Multi-UUID Confusion
If multiple sessions share the same title or context, find may return several UUIDs.
Fix: Distinguish candidates using startedAt, cwd, and matchCount fields. Do not assume sessions are duplicates based on titles alone.
Sources: skill-packages/cxs/references/failure-cookbook.md:75-77, skill-packages/cxs/SKILL.md:75-80
JSON Error Schema Reference
When automation (such as a coding agent) parses cxs output, it must handle different error shapes depending on the command executed.
| Command Group | Error Exit | Schema/Shape |
|---|---|---|
sync | stdout | `{ "error": { "code": "selector_required" |
sync (parsing errors) | stderr | SyncSummary with errors count and errorDetails[]. |
| Query Commands | stdout | { "error": { "code": "index_unavailable", "dbPath": "...", "hint": "..." } } |
| Lock Errors | stderr | { "error": <string_message> } |
Sources: skill-packages/cxs/references/failure-cookbook.md:87-105, skill-packages/cxs/references/json-schema.md:1-15
Conclusion
Effective troubleshooting in cxs relies on a "coverage-first" mindset. Before assuming a retrieval failure, the system state must be verified via status --selector. By adhering to the status -> sync -> find -> read workflow, most "missing" results can be recovered by reconciling the index with the local filesystem.
Sources: skill-packages/cxs/references/progressive-workflow.md:1-10, AGENTS.md:10-15