Summary
Errors are prose hints; exit codes are coarse (DatabaseError=3 etc.) and don't distinguish "DB not found" from "DB locked" from "schema too new." Scripts and agents resort to substring-matching English error text. There's no stable machine-readable error-code taxonomy.
Evidence
src/CodeIndex/Cli/QueryCommandRunner.cs:3150-3185 (and similar error sites) — emit prose only.
Impact
- CI scripts that need to retry-on-DB-locked vs fail-on-DB-missing have to substring-match.
- Agents (Claude / Cursor / etc.) cannot programmatically classify failure modes.
Proposed direction
- Define a stable taxonomy:
E001_DB_NOT_FOUND, E002_DB_LOCKED, E003_SCHEMA_TOO_NEW, etc.
- Include the code in human output (
Error [E002]: …) and in --json error envelopes.
- Document the taxonomy in DEVELOPER_GUIDE.md.
Repro env
- Branch:
main @ 2ee912d (release v1.21.0)
Summary
Errors are prose hints; exit codes are coarse (
DatabaseError=3etc.) and don't distinguish "DB not found" from "DB locked" from "schema too new." Scripts and agents resort to substring-matching English error text. There's no stable machine-readable error-code taxonomy.Evidence
src/CodeIndex/Cli/QueryCommandRunner.cs:3150-3185(and similar error sites) — emit prose only.Impact
Proposed direction
E001_DB_NOT_FOUND,E002_DB_LOCKED,E003_SCHEMA_TOO_NEW, etc.Error [E002]: …) and in--jsonerror envelopes.Repro env
main@ 2ee912d (release v1.21.0)