Skip to content

fix: improve error messages — fix ContextError/ResolutionError misuse#456

Merged
BYK merged 1 commit intomainfrom
fix/error-message-patterns
Mar 18, 2026
Merged

fix: improve error messages — fix ContextError/ResolutionError misuse#456
BYK merged 1 commit intomainfrom
fix/error-message-patterns

Conversation

@BYK
Copy link
Member

@BYK BYK commented Mar 18, 2026

Problem

The ContextError and ResolutionError classes produce structured Try: ... Or: ... error messages, but they're misused in ~15 call sites, producing confusing output. Real Sentry issues confirm this affects hundreds of users:

  • CLI-7V (127 events, 35 users): Project is required. Specify it using: No project 'patagonai' found...
  • CLI-4A (21 events, 13 users): Project 'AGENT-API' not found is required.
  • CLI-EZ: Trace ID and span ID is required. (grammar) + irrelevant DSN alternatives

Changes

Error class fixes:

  • Fix grammar: "X and Y is required""are required" for compound resources
  • Convert 8 ContextError misuses to ResolutionError (org-list, project/list, issue/list, project/create, resolve-team, project/view, resolve-target)
  • Convert pagination cursor error to ValidationError
  • Pass alternatives: [] at 14 sites where DSN hints are irrelevant (Trace ID, Log ID, Event ID, Span ID)

event view enhancement:

  • Issue URLs (/issues/123/) now fetch the latest event via getLatestEvent() instead of throwing a confusing error about missing event IDs

Prevention measures:

  • Runtime assertion in ContextError constructor: command must be single-line (throws on \n)
  • CI check script (script/check-error-patterns.ts) scanning for multiline ContextError commands and ad-hoc Try: patterns in CliError
  • Added check:errors step to CI workflow
  • Updated AGENTS.md with error class selection guidance

Fixes CLI-7V, CLI-4A, CLI-EZ, CLI-CC, CLI-DQ

@github-actions
Copy link
Contributor

github-actions bot commented Mar 18, 2026

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).


Bug Fixes 🐛

  • Improve error messages — fix ContextError/ResolutionError misuse by BYK in #456

🤖 This preview updates automatically when you update the PR.

@BYK BYK force-pushed the fix/error-message-patterns branch from 707a57c to b992f50 Compare March 18, 2026 00:45
@github-actions
Copy link
Contributor

github-actions bot commented Mar 18, 2026

Codecov Results 📊

116 passed | Total: 116 | Pass Rate: 100% | Execution Time: 0ms

📊 Comparison with Base Branch

Metric Change
Total Tests
Passed Tests
Failed Tests
Skipped Tests

✨ No test changes detected

All tests are passing successfully.

✅ Patch coverage is 97.80%. Project has 1139 uncovered lines.
✅ Project coverage is 95.2%. Comparing base (base) to head (head).

Files with missing lines (4)
File Patch % Lines
resolve-target.ts 82.72% ⚠️ 117 Missing
arg-parsing.ts 94.41% ⚠️ 19 Missing
org-list.ts 95.40% ⚠️ 18 Missing
view.ts 93.97% ⚠️ 12 Missing
Coverage diff
@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    95.19%    95.20%    +0.01%
==========================================
  Files          175       175         —
  Lines        23699     23729       +30
  Branches         0         0         —
==========================================
+ Hits         22560     22590       +30
- Misses        1139      1139         —
- Partials         0         0         —

Generated by Codecov Action

Fix the 'Try: ... Or: ...' error message pattern that produced confusing
output for hundreds of users (CLI-7V: 127 events, CLI-4A: 21 events, etc).

Problems fixed:
- ContextError misused for resolution failures, producing messages like
  'Project is required. Specify it using: No project found...'
- Grammar: 'Trace ID and span ID is required' → 'are required'
- Irrelevant DSN/project alternatives shown for missing positional IDs
- Ad-hoc 'Try:' strings in raw CliError bypassing structured errors
- Pagination cursor using ContextError instead of ValidationError
- event view throwing confusing error for issue URLs (now fetches latest event)

Prevention measures:
- Runtime assertion in ContextError constructor: command must be single-line
- CI check script (check:errors) scanning for multiline ContextError commands
  and ad-hoc 'Try:' patterns in CliError
- Improved JSDoc explaining when to use ContextError vs ResolutionError
- AGENTS.md updated with error class selection guidance

Fixes CLI-7V, CLI-4A, CLI-EZ, CLI-CC, CLI-DQ
@BYK BYK force-pushed the fix/error-message-patterns branch from b992f50 to 5704b5e Compare March 18, 2026 00:49
@BYK BYK marked this pull request as ready for review March 18, 2026 00:58
@BYK BYK merged commit 4bba476 into main Mar 18, 2026
22 checks passed
@BYK BYK deleted the fix/error-message-patterns branch March 18, 2026 01:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant