troubleshoot

name	troubleshoot
description	Diagnose common cqs issues — stale index, model download, schema mismatch, connection issues.
disable-model-invocation	false
argument-hint

Troubleshoot

Guided diagnosis of common cqs issues. Run through checks in order, stop at first problem found.

Checklist

1. Is cqs installed and working?

cqs --version

If not found: cargo install --path . (from source) or check ~/.cargo/bin/ is in PATH.

2. Is the project initialized?

ls -la .cqs/ && cat .cqs/active_slot 2>/dev/null
ls -la .cqs/slots/$(cat .cqs/active_slot 2>/dev/null || echo default)/ 2>/dev/null

The index lives in the active slot: .cqs/slots/<name>/index.db plus HNSW sidecars (index.hnsw*; legacy pre-slot layouts kept files at .cqs/ top level). If missing: cqs init && cqs index.

3. Is the index populated?

Run cqs stats. Check:

• Chunk count > 0
• Last update is recent
• Expected languages are present

If empty: cqs index to rebuild.

4. Schema version mismatch?

cqs stats 2>&1

If you see "SchemaMismatch" or "SchemaNewerThanCq":

• Older schema: Run /migrate to upgrade
• Newer schema: Update cqs binary to latest version

Current schema version: check src/store/helpers/mod.rs for CURRENT_SCHEMA_VERSION.

5. Model downloaded?

cqs doctor   # checks model, index, hardware in one pass
ls -la ~/.cache/huggingface/hub/models--onnx-community--embeddinggemma-300m-ONNX/

Default model is EmbeddingGemma-300m (since v1.35.0); alternative presets via CQS_EMBEDDING_MODEL / --model live under their own models--* dirs. If missing or incomplete, cqs downloads on first use. Check network access to huggingface.co. If corrupted: delete the directory and let cqs re-download (blake3 checksums verify integrity).

6. Daemon mode working?

cqs ping
systemctl --user status cqs-watch

cqs ping should report a connected daemon and a sub-100ms round-trip. Common issues:

• Daemon not running: systemctl --user start cqs-watch (or cqs watch --serve ad hoc)
• Stale socket from a crash: systemctl --user restart cqs-watch
• Want to bypass the daemon for one command: CQS_NO_DAEMON=1 cqs <cmd>
• LLM enrichment failing: check ANTHROPIC_API_KEY is set (see SECURITY.md)

7. Index stale?

Compare cqs stats last update time vs recent file modifications. Fix: cqs index (one-time) or cqs watch (continuous).

8. References broken?

cqs ref list

Check that source paths still exist and chunk counts are > 0. If source moved: cqs ref remove <name> and re-add with new path.

Report

After running checks, summarize:

• What was checked
• What failed (if anything)
• What was fixed or needs fixing