Diagnostics & Troubleshooting
Troubleshooting
When something goes wrong, sqry troubleshoot generates a diagnostic bundle with everything needed to debug the issue:
sqry troubleshoot
The bundle includes:
- System info (OS, architecture, CPU count)
- sqry version and build type
- Sanitized configuration (no secrets)
- Recent usage events (last 24 hours by default)
- Recent error logs
Options
# Write to a specific file
sqry troubleshoot -o /tmp/sqry-diag.json
# Preview what would be collected without writing
sqry troubleshoot --dry-run
# Include execution traces for deeper debugging
sqry troubleshoot --include-trace
# Expand the time window
sqry troubleshoot --window 72h
The output is JSON and safe to share — file paths and query content are sanitized.
Usage insights
sqry tracks anonymous usage patterns locally to help you understand how you use the tool. No data is sent over the network.
# View this week's usage summary
sqry insights show
# View a specific week
sqry insights show --week 2026-W09
# Check storage usage
sqry insights status
# Remove old data
sqry insights prune --older 90d
# Disable insights collection
sqry insights config --disable
Insights include:
- Query frequency by command type
- Average query latency
- Most-used predicates and fields
- Index rebuild frequency
- Cache hit rates
Query history
sqry records every query automatically (unless SQRY_NO_HISTORY=1 is set). Sensitive data like API keys and tokens are redacted before storage.
# List recent queries
sqry history list
sqry history list --limit 50
# Search history by pattern
sqry history search "callers:"
# View history statistics
sqry history stats
# Clear old entries
sqry history clear --older 30d
# Clear all history
sqry history clear
History is stored at .sqry/graph/history/ and persists across sessions. The interactive shell and batch commands both record to the same history.
Index repair
If the index becomes corrupted — for example, after a crash during indexing or a disk error — sqry repair can fix common issues without a full rebuild:
# Preview what would be fixed
sqry repair --dry-run
# Fix all known issues
sqry repair --fix-all
# Fix specific issues
sqry repair --fix-orphans # remove references to deleted files
sqry repair --fix-dangling # remove edges pointing to missing nodes
sqry repair --recompute-checksum # recalculate integrity checksums
If repair cannot fix the issue, rebuild from scratch with sqry index --force ..
Index validation
Validation runs when the index is loaded for queries. Three strictness levels:
| Level | Behavior |
|---|---|
warn (default) | Log warnings, continue with best-effort results |
fail | Abort the query if corruption is detected |
off | Skip validation entirely (fastest) |
# Strict mode with automatic rebuild on failure
sqry query "kind:function" --validate=fail --auto-rebuild
# Skip validation for maximum speed
sqry query "kind:function" --validate=off
Tunable thresholds control what counts as corruption:
| Flag | Default | Description |
|---|---|---|
--threshold-dangling-refs | 0.05 | Fraction of dangling references before flagging |
--threshold-orphaned-files | 0.20 | Fraction of orphaned files before flagging |
--threshold-id-gaps | 0.10 | Fraction of ID gaps before flagging |
For CI, use --validate=fail --auto-rebuild to guarantee correct results.
Incremental indexing
After the initial sqry index ., subsequent updates only process changed files:
# Incremental update (default)
sqry update .
# Show statistics for the update
sqry update . --stats
# Force full reparse (disable incremental)
sqry update . --no-incremental
sqry detects changes using a git-aware backend by default: it runs git diff to find added, removed, modified, and renamed files. If git is not available or disabled, it falls back to BLAKE3 content hashing.
Git backend configuration
| Variable | Default | Description |
|---|---|---|
SQRY_GIT_BACKEND | auto | Backend: auto (git if available), git, none (hash-only) |
SQRY_GIT_RENAME_SIMILARITY | 50 | Rename detection threshold (0–100) |
SQRY_GIT_MAX_OUTPUT_SIZE | 10 | Max git output in MB (1–100) |
SQRY_GIT_TIMEOUT_MS | 30000 | Git command timeout |
SQRY_GIT_INCLUDE_UNTRACKED | 1 | Include untracked files in change detection |
Analysis precomputation
sqry index already builds the graph structures that accelerate cycle detection, reachability, and path queries. sqry analyze is now the explicit rebuild path when you want to regenerate those artifacts with different tuning settings:
sqry analyze .
The analysis layer includes:
- CSR adjacency matrices — compressed sparse row format for fast neighbor lookups
- Strongly connected components (Tarjan’s algorithm) — used by cycle detection
- Condensation DAGs — the acyclic graph of SCCs
- 2-hop interval labels — reachability preprocessing for instant path existence checks
After sqry index ., queries like trace-path, cycles, and is-node-in-cycle already benefit from these precomputed structures. Run sqry analyze when you want to force a rebuild, validate the analysis output, or apply different analysis-budget settings.
sqry analyze reads the current snapshot and rewrites the analysis files under .sqry/analysis/. In normal workflows, build or refresh the index with sqry index . or sqry update . and only use sqry analyze for explicit re-analysis.